home *** CD-ROM | disk | FTP | other *** search
/ The PC-SIG Library 9 / The PC-SIG Library on CD ROM - Ninth Edition.iso / 801_900 / DISK0829 / DISK0829.ZIP / MANUAL.ARC / MANUAL
Text File  |  1987-05-26  |  143KB  |  5,301 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.                              THE ME TEXT EDITOR
  11.     
  12.            (C) COPYRIGHT 1986   MARC ADLER     ALL RIGHTS RESERVED
  13.     
  14.                            MAGMA SOFTWARE SYSTEMS
  15.                              138-23 HOOVER AVE.
  16.                            JAMAICA, NEW YORK 11435
  17.                                (718) 793 - 5670
  18.     
  19.  
  20.  
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.     
  73.     
  74.                               TABLE OF CONTENTS
  75.     
  76.     Installing the Editor...................................Chapter 0
  77.     
  78.     Introduction to the ME Editor...........................Chapter 1
  79.     
  80.     The ME Help Facility....................................Chapter 2
  81.     
  82.     Character-Oriented Commands.............................Chapter 3
  83.     
  84.     Line-Oriented Commands..................................Chapter 4
  85.     
  86.     Block Commands..........................................Chapter 5
  87.     
  88.     Input/Output Commands...................................Chapter 6
  89.     
  90.     Searching and Substituting..............................Chapter 7
  91.     
  92.     Keyboard Macros.........................................Chapter 8
  93.     
  94.     Multi-Window Editing....................................Chapter 9
  95.     
  96.     Miscellaneous Commands..................................Chapter 10
  97.     
  98.     Editor Options..........................................Chapter 11
  99.     
  100.     Introduction to the Macro Language......................Chapter 12
  101.     
  102.     Macro Language - Editor Services........................Chapter 13
  103.     
  104.     Macro Language - Buffer Services........................Chapter 14
  105.     
  106.     Macro Language - Primitives.............................Chapter 15
  107.     
  108.     Remapping the Keyboard..................................Appendix A
  109.     
  110.     The CTags Utility.......................................Appendix B
  111.     
  112.     
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.                                ME USERS MANUAL
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.                INSTALLATION INSTRUCTIONS FOR THE ME EDITOR
  135.     
  136.         On  the enclosed disk, you will find the editor, help files, macro
  137.     files, macro compiler, and several other utility  files.  These  files
  138.     are :
  139.     
  140.             INSTALL.BAT - a batch file to perform the installation process
  141.     
  142.             ME.EXE - the editor program
  143.             MACCOMP.EXE - the macro compiler
  144.     
  145.             KEYCHART - a table showing the editor commands
  146.     
  147.             \HELP\MEHELP.xxx - the editor help files
  148.             \MACROS\* - the macro source files
  149.                     *.EXM - the macro executable files
  150.     
  151.             CONFIG.ME - the editor configuration file
  152.     
  153.             MANUAL - the printable documentation for the editor
  154.     
  155.             KEYREMAP.ARC - keyboard remapping utilities
  156.     
  157.         If  you  ordered  the  source  code,  then  there  is another disk
  158.     enclosed which has the source code on it.
  159.     
  160.         The executable file is called ME.EXE. This should be placed in one
  161.     of the directories which is included  in  your  DOS  search  path,  or
  162.     placed in your current directory. To find out what your current search
  163.     path  is,  type "PATH" from the DOS prompt. Refer to the MS/DOS manual
  164.     if you need help on changing your search path.
  165.     
  166.     
  167.                             AUTOMATIC INSTALLATION
  168.     
  169.         There  is  a  batch  file  on  the  distribution  diskette  called
  170.     INSTALL.BAT. Running this batch file will  automatically  install  the
  171.     editor  in the proper subdirectories. This batch file assumes that you
  172.     have a hard disk drive  C:.  If  you  dont,  then  you  can  edit  the
  173.     INSTAL.BAT file. You can also follow the instructions contained in the
  174.     INSTALL.BAT file, and manually install the files.
  175.     
  176.     
  177.                            THE ENVIRONMENT VARIABLE
  178.     
  179.         During an editing session, the editor may have to look for several
  180.     files,  such  as macro files or help files. Normally, the editor first
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.     Installing the Editor                           Chapter 0   Page 1
  188.  
  189.  
  190.                                ME USERS MANUAL
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.     searches the current directory, then will  search  all  subdirectories
  198.     that are listed in your PATH environment variable. 
  199.     
  200.         To  speed  up  searching,  the editor will look for an environment
  201.     variable called ME. The value of this variable should be the name of a
  202.     subdirectory which the editor should look in first in order to  locate
  203.     certain files. For instance, if I have a subdirectory called \ME which
  204.     contains  all  of  the editor's files, then in my AUTOEXEC.BAT file, I
  205.     might have the statement "set ME=c:\ME".
  206.     
  207.     
  208.                             THE CONFIGURATION FILE
  209.     
  210.         Among the all of the files is one file which is important (but not
  211.     required) for configuring your ME editing session. This file is called
  212.     CONFIG.ME. 
  213.     
  214.         The CONFIG.ME file should be placed in the subdirectory which  you
  215.     have  specified  with  the  ME environment variable. If you don't have
  216.     this variable, you can put the  CONFIG.ME  file  in  any  subdirectory
  217.     along your DOS search path.
  218.     
  219.         Although  you  can alter the values of the parameters in this file
  220.     without reading the manual, it's recommended that you read the  manual
  221.     and have a little bit of practice with ME before modifying them. 
  222.  
  223.  
  224.  
  225.  
  226.  
  227.  
  228.  
  229.  
  230.  
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.  
  247.  
  248.  
  249.  
  250.     Installing the Editor                           Chapter 0   Page 2
  251.  
  252.  
  253.                                ME USERS MANUAL
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.                                  INTRODUCTION
  261.     
  262.         ME  (short for Macro Editor) is a programmer's text editor written
  263.     by a professional programmer for programmers. Although this editor  is
  264.     inexpensive, its power rivals that of much more expensive editors.  We
  265.     strive  to  keep the editor state-of-the-art and bug-free. If you have
  266.     any comments at all about the editor, please feel free to contact us.
  267.     
  268.         This  editor  has  been  written specifically for the IBM Personal
  269.     Computer, and takes advantage of some of its  features,  like  memory-
  270.     mapped  display,  fast  string  operations, etc. The editor is written
  271.     mostly in the C programming  language,  with  some  assembly  language
  272.     routines  to  speed  things  up.  The  version  of  C compiler used is
  273.     Microsoft version 4.0. 
  274.     
  275.         To  run  the editor, you need an IBM PC, XT or AT (or compatible),
  276.     and at least 192K of memory. You should be using DOS 2.0  or  greater.
  277.     The  editor  uses direct screen writes for speed, and assumes that the
  278.     video memory for the color card starts at address B800, and  the  mono
  279.     card  memory starts at B000. If you have an Enhanced Graphics Adapter,
  280.     the editor's <TOGGLE EGA> command can be used  to  switch  the  screen
  281.     into a 43 line display.
  282.     
  283.         All  operations  on  text  work extremely fast. All of the data is
  284.     kept in main memory  for  speed.  With  the  cost  of  memory  rapidly
  285.     decreasing, and with the new generation of CPU's which provide virtual
  286.     memory  capabilities, I have seen no need to include virtual memory in
  287.     the editor. Virtual memory also slows many operations  down,  such  as
  288.     searching  through  the entire file for a word. This is because of the
  289.     disk I/O needed to swap out a section of the file which is  not  being
  290.     used any longer, and to swap another section in. 
  291.     
  292.     
  293.                                    FEATURES
  294.     
  295.     1) Powerful C-like macro language for defining your own commands.
  296.     2) Remapable keyboard.
  297.     3) You  may  have  up  to 12 windows shown simultaneously,  with a
  298.        different file in each window. You can also enlarge any window to
  299.        occupy the whole screen.
  300.     4) Regular expression pattern matching.
  301.     5) Column block operations.
  302.     6) Keyboard macros.
  303.     7) Escape to the DOS operating system.
  304.     8) 10 "pick" buffers.
  305.     
  306.     
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.     The ME Editor                                   Chapter 1   Page 1
  314.  
  315.  
  316.                                ME USERS MANUAL
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.                               RUNNING THE EDITOR
  324.     
  325.         You can run the editor from either a floopy disk or a  hard  disk.
  326.     If  you  are  using  a  hard  disk,  you may want to create a separate
  327.     subdirectory for all of the editor files, or (most  probably)  install
  328.     the  editor  in  a subdirectory which contains most of your executable
  329.     files. (On my system, I put all the executables in a directory  called
  330.     \bin.)
  331.     
  332.         To run the editor, from the DOS prompt type
  333.     
  334.         me [options] filename [filename ...]
  335.     
  336.     where  "filename"  is the name of the file you want to edit or create.
  337.     With DOS, a filename can have up to 8 characters as the main part, and
  338.     up to 3 characters as the extension. 
  339.     
  340.         On the DOS command line, you can give the name of  more  than  one
  341.     file to edit. For instance, when you invoke the editor, you might like
  342.     to have file "FOO" in the bottom window, and the file "BAR" in the top
  343.     window. From DOS, you would type the command :
  344.     
  345.       me foo bar
  346.     
  347.         There is no wildcard expansion for the command line. Be prudent in
  348.     the  number  of  files you bring up initially, since the editor has no
  349.     virtual memory capabilities.
  350.     
  351.     Pre-loading a Macro
  352.     
  353.         If  you  use the macro facility, there may be times when you would
  354.     like one or more macro files to be  already  loaded  when  the  editor
  355.     starts  up.  To do this, use the "-l" option. ("l" stands for "load".)
  356.     Directly after the "l", you must put the name of the executable  macro
  357.     file (without the ".exm" option).
  358.     
  359.         As an example, let's assume that you have an executable macro file
  360.     called  "efuncs.exm".  To  load it in when the editor starts, type the
  361.     command
  362.     
  363.         me -lefuncs foo.c
  364.     
  365.         The arguments to "-l" may include a full path specification,  like
  366.     "\e\macros\efuncs".  There  also may be more than one "-l" argument on
  367.     the command line, such as
  368.     
  369.         me -lefuncs -l\e\macros\c foo.c
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.     The ME Editor                                   Chapter 1   Page 2
  377.  
  378.  
  379.                                ME USERS MANUAL
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.     
  387.     
  388.                               EXITING THE EDITOR
  389.     
  390.         To  exit  the  editor,  press  the  <EXIT> command. For historical
  391.     reasons, the <EXIT> command is usually tied to the keystroke <CTRL> D.
  392.     You are asked if you want to save your changes; type 'y' for  yes  and
  393.     'n' for no. Typing any other key will bring you back into the editor.
  394.     
  395.     
  396.     
  397.                                THE STATUS LINE
  398.     
  399.         The 25th line on the IBM PC is reserved for information pertaining
  400.     to   your  current  editing  session.  It  is  also  used  to  display
  401.     information about various commands, and to receive input from the user
  402.     for these commands. This line is referred to as the "status line".
  403.     
  404.         During your editing session, the status line tells you what column
  405.     of the line you are on, the current line number, how many lines  there
  406.     are in the file, whether you are in insert or overstrike mode, and the
  407.     name of the file you are editing. The status line can be distinguished
  408.     from the rest of the display because it is shown in reverse video.
  409.     
  410.         For  some  commands (like the search and substitute commands), the
  411.     status line will contain a prompt. You are then required to enter some
  412.     information on the status line. For most commands,  typing  the  <ESC>
  413.     key will abort the command.
  414.     
  415.         The rightmost part of the status  line  tells  you  if  NUM  LOCK,
  416.     SCROLL LOCK, and CAPS LOCK is on. The status line will show the letter
  417.     'N'  if  NUM  LOCK is on, the letter 'S' if SCROLL LOCK is on, and the
  418.     letter 'C' if CAPS LOCK is on. 
  419.     
  420.     
  421.     
  422.                             CUSTOMIZING THE EDITOR
  423.     
  424.         Probably the most powerful feature of the editor is the ability to
  425.     write macro programs. Many times, you will want to perform a series of
  426.     complex editing operations that may take many keystrokes. These opera-
  427.     tions may have to be repeated many times, or may be subject to certain
  428.     conditions.  If  this  series of operations is something that you need
  429.     more than once, then it may be beneficial to write a macro to do  your
  430.     task. 
  431.     
  432.  
  433.  
  434.  
  435.  
  436.  
  437.  
  438.  
  439.     The ME Editor                                   Chapter 1   Page 3
  440.  
  441.  
  442.                                ME USERS MANUAL
  443.  
  444.  
  445.  
  446.  
  447.  
  448.  
  449.         For instance, a common operation for C programmers is to take some
  450.     text  and  surround it in a comment block. (This was the first macro I
  451.     wrote.) To do this, you would move the cursor to the first line of the
  452.     block, and open up a blank line. Then, you would  type  a  slash,  and
  453.     then  would  fill  the rest of the blank line with asterisks. Then you
  454.     would move the cursor to the beginning of the next  line,  insert  one
  455.     asterisk,  move  the cursor to the end of the line, and insert another
  456.     asterisk. This would have to be done for each line of text inside  the
  457.     block.  Then, you would insert a blank line after the last line of the
  458.     block, and fill the blank line with asterisks, followed by a slash. 
  459.     
  460.          aaaaaaaa                   /***********
  461.          bbbbbbbb       becomes     * aaaaaaaa *
  462.          cccccccc                   * bbbbbbbb *
  463.                                     * cccccccc *
  464.                                     ***********/
  465.     
  466.     Since this operation is something that a C programmer does frequently, 
  467.     then this would be a candidate for a macro.
  468.     
  469.     The editor comes with a programming language  whose  syntax  resembles
  470.     the  C  programming  language. Macro programs are written in this lan-
  471.     guage, then given to the macro  compiler  to  translate  into  an  in-
  472.     termediate language. This intermediate language can be executed quick-
  473.     ly  by  the editor's macro interpreter. When you load a macro into the
  474.     editor, it is the intermediate language version which is loaded in and
  475.     executed. 
  476.     
  477.     When you start the editor,  you can indicate which macro files  should 
  478.     be loaded in with it. At any time throughout your editing session, you 
  479.     can load in any macro and execute it.  
  480.  
  481.  
  482.  
  483.  
  484.  
  485.  
  486.  
  487.  
  488.  
  489.  
  490.  
  491.  
  492.  
  493.  
  494.  
  495.  
  496.  
  497.  
  498.  
  499.  
  500.  
  501.  
  502.     The ME Editor                                   Chapter 1   Page 4
  503.  
  504.  
  505.                                ME USERS MANUAL
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.                            THE HELP FACILITY
  513.     
  514.         Among the files that you will find in  the  ME  package  are  help
  515.     files.  Each  help  file  is  called "MEHELP.xx", where xx is a one or
  516.     two-digit number. It is best to store the help files in a subdirectory
  517.     called  "\ME\HELP".  If  this  is  not possible, these files should be
  518.     stored either in your current directory, or in a directory which is in
  519.     your DOS search path. 
  520.     
  521.         When you press the <HELP>  command  (the  ALT  H  key),  ME  first
  522.     looks  in  a subdirectory called "\ME\HELP". If the help files are not
  523.     found, ME searches all of the directories in your DOS search path  for
  524.     a  file  called  "MEHELP.0".  This file contains the text for the main
  525.     help menu, and can be changed by you if you want (see below). When  ME
  526.     finds this file, it will display it on the screen, and then prompt you
  527.     for the help selection. 
  528.     
  529.         To  read  a  help file, type the number next to the help topic you
  530.     want to view. ME will then look for a file called "MEHELP.nn" where nn
  531.     is the number you just typed, and if found,  will  display  the  file.
  532.     After  you view this file, ME will re-display the main help screen and
  533.     prompt you for the next selection. 
  534.     
  535.     CHANGING THE HELP FILES
  536.     
  537.         These  help  files  are  in  ASCII form, and their contents can be
  538.     changed by using any text editor available. If you  decide  to  change
  539.     it,  then  make  sure  that  you  save  your  changes  in  ASCII  form
  540.     (especially if you use a word processor  which  writes  out  files  in
  541.     their own format).
  542.     
  543.         You  can  add  your  own  help  files,  as  long  as  you  name it
  544.     "MEHELP.xx", where xx is a one or two-digit number.  These  new  help
  545.     files  should reside in the same directory as the other help files. If
  546.     you create a new help file, you should add the entry in the help  menu
  547.     found in the file "MEHELP.0".
  548.     
  549.     
  550.                          DISCOVERING KEY ASSIGNMENTS
  551.     
  552.         The  <KEY  TO  FUNC>  function  (key ALT F1) will prompt you for a
  553.     keystroke, and will print out the macro function  which  that  key  is
  554.     associated with, if any. For instance, if after typing <ALT> <F1>, you
  555.     press <F1>, then the editor will tell you that <F1> is associated with
  556.     the  "delline()" function. Type the <ESC> key to return to the editing
  557.     session.
  558.  
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.     The ME Help Facility                            Chapter 2   Page 1
  566.  
  567.  
  568.                                ME USERS MANUAL
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.     
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.  
  603.  
  604.  
  605.  
  606.  
  607.  
  608.  
  609.  
  610.  
  611.  
  612.  
  613.  
  614.  
  615.  
  616.  
  617.  
  618.  
  619.  
  620.  
  621.  
  622.  
  623.  
  624.  
  625.  
  626.  
  627.  
  628.     The ME Help Facility                            Chapter 2   Page 2
  629.  
  630.  
  631.                                ME USERS MANUAL
  632.  
  633.  
  634.  
  635.  
  636.  
  637.  
  638.                          CHARACTER ORIENTED COMMANDS
  639.     
  640.         Normally  the  editor  is in overstrike mode. This means that when
  641.     you type a character,  it  replaces  the  character  over  the  cursor
  642.     position. 
  643.     
  644.         The <INS> key toggles the character insert mode on  and  off.  The
  645.     default  mode  (unless  changed  in  the CONFIG.ME file) is overstrike
  646.     mode. Pressing <INS> will change the mode to insert mode. Any  charac-
  647.     ters typed will push the characters beyond it rightwards. When you are
  648.     in  insert  mode,  the cursor will be block-shaped. On the other hand,
  649.     when you are in overstrike mode, the cursor will be the  the  size  of
  650.     the normal DOS cursor. 
  651.     
  652.         The  editor  considers  all  control  characters  and all extended
  653.     ASCII characters  to  be  potential  commands.  This  means  that  all
  654.     characters  whose ASCII values are between 32 and 126 will be inserted
  655.     into the file as text. To insert the other characters, use the <QUOTE>
  656.     command.
  657.     
  658.         The <QUOTE> command (key <ALT> Q) allows  you  to  insert  control
  659.     characters  into your document. After typing the <QUOTE> key, the fol-
  660.     lowing key you type will have its ASCII value inserted into the  text.
  661.     command below. You may use the  <ALT>  key  in  conjunction  with  the
  662.     numeric keypad to type in an extended character.
  663.     
  664.         Hitting  the  <RETURN> key has the effect of splitting the current
  665.     line in two, starting at the cursor position. If you are at the end of
  666.     the line, then this just has the effect of creating a new line.
  667.     
  668.         Although there can be as many as 32,767 characters  on  one  line,
  669.     please  try  to  limit the number of characters to 256. This should be
  670.     sufficient for most programming languages.
  671.     
  672.     
  673.     
  674.                               ERASING CHARACTERS
  675.     
  676.         The <DEL> key deletes the character under the cursor. If the  cur-
  677.     sor is  at the end of a line, then the next line will be joined to the
  678.     current line. 
  679.     
  680.         The <BACKSPACE> key deletes the character to the left of the  cur-
  681.     sor. If the cursor is at the left margin, the line will be joined with
  682.     the previous line. 
  683.     
  684.  
  685.  
  686.  
  687.  
  688.  
  689.  
  690.  
  691.     Character Oriented Commands                     Chapter 3   Page 1
  692.  
  693.  
  694.                                ME USERS MANUAL
  695.  
  696.  
  697.  
  698.  
  699.  
  700.  
  701.         The <DEL WORD> command (key <SH> <DEL>) deletes the word under the
  702.     cursor. 
  703.     
  704.         The  <DEL  EOL> command (key <SH> KEYPAD 5) deletes all characters
  705.     from the cursor position to the end of the line.
  706.     
  707.     
  708.                                    WORDWRAP
  709.     
  710.         The  editor  gives  you very basic word processing capabilities by
  711.     using the wordwrap toggle in conjunction with altering the right  mar-
  712.     gin.  The  <TOGGLE  WORDWRAP>  command  (the  CTRL  W key) will toggle
  713.     wordwrap mode on and off. If wordwrap mode is on, then  you  will  see
  714.     the letter 'W' on the status line in the "mode" area. 
  715.     
  716.         To  change  the  right margin, use the <RIGHT MARGIN> command (the
  717.     ALT M key). You can type in the  numerical  value  of  the  new  right
  718.     margin.
  719.     
  720.         If wordwrap mode is on, and if you type past the right margin, the
  721.     word will wrap to the next line.
  722.     
  723.                                   8 BIT MODE
  724.     
  725.         All  keystrokes  which  produce a value over 127 are considered by
  726.     the editor to be commands. If you want to  insert  an  extended  ASCII
  727.     code into your document, you usually use the <QUOTE CHAR> command (the
  728.     <ALT>  Q  key).  However, there may be times when you wish to insert a
  729.     sequence of extended ASCII character without having to  type  <ALT>  Q
  730.     before each one.
  731.     
  732.         The  <ALT>  7  key toggles between 7 bit mode and 8 bit mode. When
  733.     you press the <ALT> 7 key to toggle 8 bit mode, the  number  '8'  will
  734.     appear  on  the status line in the mode section. This means that 8 bit
  735.     mode is ON. If you press <ALT> 7 again, the 8 will go away and regular
  736.     7 bit mode will be enabled. 
  737.     
  738.         As long as 8 bit mode is ON, then  you  can  type  extended  ASCII
  739.     sequences  without  having  to  hit  <ALT> Q before each character. To
  740.     enter an extended ASCII code,  you  can  use  the  numeric  keypad  in
  741.     conjunction  with  the ALT key, or you may type any function key which
  742.     produces a character above 127. REMEMBER - all of the editors  command
  743.     will be DISABLED until you toggle back to 7 bit mode.
  744.     
  745.     
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.     Character Oriented Commands                     Chapter 3   Page 2
  755.  
  756.  
  757.                                 ME USERS MANUAL
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.                              LINE-ORIENTED COMMANDS
  765.      
  766.          Since most programming languages  tend  to  be  line  oriented,  a
  767.      programmer's  text  editor  should be able to insert, delete, and move
  768.      lines easily. See the section on block commands to see how to mark and
  769.      move a series of lines.
  770.      
  771.          The  <INSERT LINE> command (key F2) inserts a blank line above the
  772.      cursor. If the auto-indent option is on, then the cursor will move  to
  773.      the  column  corresponding  to  the  first  non-blank character of the
  774.      previous line.
  775.      
  776.          The <APPEND LINE> command (SHIFT F2) will place a blank line below
  777.      the current line. 
  778.      
  779.          The  <DUPLICATE  LINE> command (ALT F9) will duplicate the current
  780.      line and place the copy on the next line. This is equivalent to press-
  781.      ing <COPY>, then <DOWN>, then <PUT>. 
  782.      
  783.          The <DELETE LINE> command (key F1) deletes the line which the cur-
  784.      sor is on. This command can be preceded by  a  count  (ie  -  <ESC>  3
  785.      <DELETE LINE> deletes 3 lines). 
  786.      
  787.          The  <UNDO>  command  (key <ALT> U) allows you to restore the last
  788.      lines or block that was deleted. Buffer 9  is  reserved  as  the  place
  789.      where deleted lines  are  stored.  If  you  press  the  <DELETE  LINE>
  790.      command  5  times,  then  those  5  lines can be restored by using the
  791.      <UNDO> command.
  792.      
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.  
  801.  
  802.  
  803.  
  804.  
  805.  
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.  
  814.  
  815.  
  816.  
  817.      Line Oriented Commands                          Chapter 4   Page 1
  818.  
  819.  
  820.                                 ME USERS MANUAL
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.                       CUTTING, PASTING, AND BLOCK COMMANDS
  828.      
  829.          A "buffer" is a block of memory that holds text. The editor  comes
  830.      equipped  with several pre-defined system buffers used to hold "scrap"
  831.      pieces of text. These buffers are referred to as "pick  buffers".  The
  832.      pick  buffers  are  common to all of the windows in the editor. Hence,
  833.      text that a pick buffer contains can be pasted into any window.
  834.      
  835.          There  are  ten "pick buffers" which you can use to save text when
  836.      you are cutting and pasting text. The buffers are numbered from  0  to
  837.      9,  and  the  default  buffer is number 0. To change the number of the
  838.      current pick buffer, use the <CHG PICK BUFFER> command.  This  command
  839.      is initially assigned to the <CTRL> F7 key.
  840.      
  841.          The  <PICK+CLEAR> command (key F8) clears the current pick buffer,
  842.      and places the current line in the buffer. The line  is  then  deleted
  843.      from  the  file.  This  command  is useful as the first step of moving
  844.      lines from one location to another.
  845.      
  846.          The <PICK+APPEND> command (key <SH> f8) appends the  current  line
  847.      to  the current pick buffer. The current line is then deleted from the
  848.      file. 
  849.      
  850.          The   <COPY>  command  (key  <SH>  F9)  does  the  same  thing  as
  851.      <PICK+CLEAR> except the current line is NOT deleted from the file. 
  852.      
  853.          All  three  of  the above commands may take an optional count (for
  854.      example, <ESCAPE> 3 <PICK+CLEAR> will pick and delete the  next  three
  855.      lines). There are ten pick buffers, numbered 0 through 9. Buffer 9 has
  856.      a  special  use,  in  that  it  stores  lines and blocks that you have
  857.      deleted with either the <DELETE  LINE>  command,  or  a  delete  block
  858.      operation.  The  <UNDO>  command  looks  in  buffer  9 for lines to be
  859.      reinstated. Buffer 0 is the default buffer.
  860.      
  861.      
  862.                                  MARKING BLOCKS
  863.      
  864.          There  are  two  types  of text blocks that you can work with. One
  865.      kind is a contiguous block, starting at one character  and  ending  at
  866.      another. The other kind of block is a rectangular block.
  867.      
  868.          The <MARK> command (key F7) defines a block of text to perform  an
  869.      operation  on.  Move  to  start of the block and press <MARK> - a grey
  870.      rectangle will be shown where you marked the text. Then  move  to  the
  871.      end  of  the  block  and  press <MARK> again. The entire block will be
  872.      highlighted. You are prompted for the  operation  to  perform  on  the
  873.      block.  The  current operations are pick & clear, pick & append, copy,
  874.  
  875.  
  876.  
  877.  
  878.  
  879.  
  880.      Working with Blocks                             Chapter 5   Page 1
  881.  
  882.  
  883.                                 ME USERS MANUAL
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.      delete, or write to a file.  If you want to abort the operation, press
  891.      either <ESC> or <CTRL> D. 
  892.      
  893.          The  <RECT  MARK>  command  (key  <SH>  F7)  is  like  the  <MARK>
  894.      operation, except it defines a rectangular block. This is  useful  for
  895.      manipulating  columns. If you pick or delete a rectangular block, then
  896.      you are asked if you want to delete the column or replace  the  column
  897.      with blanks. The default is to delete the column.
  898.      
  899.      
  900.                                   PASTING TEXT
  901.      
  902.          The  <PUT> command (key F9) allows you to take the contents of the
  903.      current pick buffer and place it in your text. (Remember that you  can
  904.      change the current pick buffer with the <CHG  PICK  BUFFER>  command.)
  905.      
  906.          There are three ways that you can put text back into the file. The
  907.      first (and most common) way is to  INSERT  the  lines  from  the  pick
  908.      buffer above the current line. The second  method  is  to  insert  the
  909.      text  at  the  current  cursor  position, pushing the old texst to the
  910.      right. The third method is to overlay the text, wiping  out  any  text
  911.      that  was  there before. The latter two methods are used predominantly
  912.      with COLUMNS of text.
  913.       
  914.          Since most programming languages are line oriented, then the first
  915.      method  of  pasting  the  text  is the one that will be used most fre-
  916.      quently. There is an editor variable which controls whether or not you
  917.      will be prompted for the method you want when you hit the  <PUT>  com-
  918.      mand. This variable, the 'pu' variable in the options menu, is normal-
  919.      ly  off.  If the editor detects that the text that resides in the pick
  920.      buffer was NOT columnar data, and if the 'pu' variable  is  OFF,  then
  921.      the editor will not prompt you for the pasting method. 
  922.      
  923.          If  the 'pu' variable is ON, then you are asked if you want to in-
  924.      sert the text above the cursor, insert the text to the  right  of  the
  925.      cursor, or overlay the text at the cursor position (only if you used a
  926.      <RECT MARK> to extract a column).  These  choices  are  labelled  'i',
  927.      'p',  and  'o'.  The  default is to insert the text above the cursor -
  928.      just hit the <RETURN> key to insert.
  929.      
  930.      
  931.                          OPERATIONS ON GROUPS OF LINES
  932.      
  933.          Since  the structure of computer programs is more oriented towards
  934.      LINES rather than a STREAM of text,  the  editor  provides  operations
  935.      which  you can perform on a disjoint or contiguous set of lines. These
  936.      operations are the same ones as you find withy the  block  operations.
  937.      They are :
  938.  
  939.  
  940.  
  941.  
  942.  
  943.  
  944.      Working with Blocks                             Chapter 5   Page 2
  945.  
  946.  
  947.                                 ME USERS MANUAL
  948.  
  949.  
  950.  
  951.  
  952.  
  953.  
  954.      
  955.              - Delete a group of lines (F1)
  956.              - Append lines to a pick buffer (SH F8)
  957.              - Place lines in a pick buffer (erasing the pick buffer first)
  958.                 (F8)
  959.              - Copy lines into a pick buffer (SH F9)
  960.              - Write marked lines to a file (ALT W)
  961.      
  962.          Normally,  all of the above operations operate on a single line at
  963.      a time (unless preceeded by a count operation). However, if the editor
  964.      detects that there are marked lines, then the operations are performed
  965.      on the marked lines.
  966.      
  967.          There are three keystrokes used to mark lines. They are :
  968.      
  969.              <MARK LINE> (ALT F7) - marks the current line. The  line  will
  970.      be highlighted.
  971.              <MARK  GROUP> (ALT F8) - marks all lines from the current line
  972.      until the previous marked line. For instance, if  you  mark  line  10,
  973.      move the cursor to line 15, and press ALT F8, then lines 11 through 15
  974.      will  be  marked.
  975.              <CLEAR  MARKS>  (CTRL  F8) - this keystroke is usually used to
  976.      erase a block mark that was previously entered. However, if the editor
  977.      sees that lines are marked, then the lines will be unmarked. 
  978.      
  979.          The  <DUPLICATE LINE> command (the ALT F9 key) provides a shortcut
  980.      for copying a group of marked lines to the  current  cursor  position.
  981.      Mark  the  lines  which  you want to make a copy of, and then move the
  982.      cursor to the line where you would like the copied  lines  to  appear.
  983.      Press  <DUPLICATE  LINE>,  and  the  lines will be inserted before the
  984.      line which the cursor is on.
  985.      
  986.          If   you   are   programming  in  the  macro  language,  then  the
  987.      is_linemarked() primitive is used  to  tell  if  the  current  lie  is
  988.      marked.  It  returns  a  zero  if  the  line is not marked, or else it
  989.      returns a non-zero.
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.  
  999.  
  1000.  
  1001.  
  1002.  
  1003.  
  1004.  
  1005.  
  1006.  
  1007.      Working with Blocks                             Chapter 5   Page 3
  1008.  
  1009.  
  1010.                                ME USERS MANUAL
  1011.  
  1012.  
  1013.  
  1014.  
  1015.  
  1016.  
  1017.                             INPUT/OUTPUT COMMANDS 
  1018.     
  1019.         The  input  and  ouput  commands  support  full  DOS  path  names,
  1020.     including a drive specifier.
  1021.     
  1022.         The <READ> command (key <SH> F10) reads a  file  and  inserts  the
  1023.     contents before the current line. The file should be  an  ASCII  file,
  1024.     although it may have embedded control characters.
  1025.     
  1026.         The  <WRITE> command (key F10) allows you to save the file you are
  1027.     editing to another file. You can print the  file  by  specifying  your
  1028.     printer  device  as the output file. The name of the printer device is
  1029.     usually PRN or LPT1.
  1030.     
  1031.         The <WRITE BUFFER> command (key <ALT> W) does the  same  thing  as
  1032.     <WRITE>  but the lines are taken from the current pick buffer (see the
  1033.     help  on  block commands). If the editor detects that there are marked
  1034.     lines, then the <WRITE BUFFER> command will write the marked lines out
  1035.     to a file.
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.  
  1065.  
  1066.  
  1067.  
  1068.  
  1069.  
  1070.     Input/Output Commands                           Chapter 6   Page 1
  1071.  
  1072.  
  1073.                                 ME USERS MANUAL
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.                              SEARCHING AND SUBSTITUTING
  1081.      
  1082.          The editor allows you to search forwards or backwards through  the
  1083.      file for a certain pattern. You can specify whether the search is case
  1084.      insensitive  or  not.  The  editor  allows  you to use a very powerful
  1085.      mechanism called "regular expressions".
  1086.      
  1087.          The  use  of regular expressions has become very popular since the
  1088.      use of UNIX has become widespread. Although most operating systems let
  1089.      you specify wildcards, UNIX carries the class of expressions  further.
  1090.      For  a  good  discussion  of  regular expressions, please see the book
  1091.      "Software Tools" by Kernigan and Ritchie, published by Addison Wesley.
  1092.      (UNIX is a trademark of AT&T.)
  1093.      
  1094.          The process of searching is done much faster if the editor detects
  1095.      that  the  pattern you specify does not contain any regular expression
  1096.      metacharacters. The editor uses an assembly language  procedure  which
  1097.      makes use of the fast 8088 string comparison instructions.
  1098.      
  1099.          When you type one of the search commands, the editor shows you the
  1100.      previous pattern that you typed. If  you  want  to  use  that  pattern
  1101.      again, then just press <RETURN>.
  1102.      
  1103.      
  1104.                                    METACHARACTERS
  1105.      
  1106.      ?       Matches any character
  1107.      *       Matches zero or more occurences of the previous pattern.
  1108.      +       Matches one or more occurences of the previous pattern.
  1109.      [A-Z]   A character class. Matches any character within the class.
  1110.      [^A-Z]  Matches any character NOT IN the class.
  1111.      \       Takes the next character literally.
  1112.      ^       Anchors the match at the beginning of the line.
  1113.      $       The match succeeds if at the end of the line.
  1114.      a|b     Matches pattern a or pattern b.
  1115.      \(a\)   Tags pattern a.
  1116.      \n      Refers to the tagged pattern n. N is a number from 1 to 9.
  1117.      
  1118.      
  1119.                                       EXAMPLES
  1120.      
  1121.      abc             Matches 'abc'.
  1122.      ^$              Matches a line with no characters.
  1123.      ^abc            Matches a line which starts with 'abc'.
  1124.      ^abc$           Matches a line which contains only 'abc'.
  1125.      [A-Z][0-9]      Matches a capital letter followed by a digit.
  1126.      [^A-Za-z0-9]    Matches a character which is not alphanumeric.
  1127.  
  1128.  
  1129.  
  1130.  
  1131.  
  1132.  
  1133.      Searching and Substituting                      Chapter 7   Page 1
  1134.  
  1135.  
  1136.                                 ME USERS MANUAL
  1137.  
  1138.  
  1139.  
  1140.  
  1141.  
  1142.  
  1143.      be?t            Matches 'be', followed by any character, followed by a 't'.
  1144.                              (ie - bert, belt, bent).
  1145.      ab*c            Matches an 'a', followed by zero or more 'b's, followed by
  1146.                              a 'c'.
  1147.      ab\*c           Matches 'ab*c'.
  1148.      [A-Z][A-Z]*[.?,! ]      Matches a capitalized word.
  1149.      if|else         Matches the word 'if' or the word 'else'.
  1150.      if|else|for     Matches 'if' or 'else' or 'while'.
  1151.      \(abc\)[0-9]\1  Matches 'abc', any digit, then 'abc'.
  1152.      \([A-Z]+\)?*\1  Matches a line which case two or more occurences of the
  1153.                      same upper-case word.
  1154.      
  1155.      
  1156.          You  are  also allowed to search for a pattern and replace it with
  1157.      some text. The substitution commands prompt you for the search pattern
  1158.      first, and then the text to be  substituted.  Then,  you  can  specify
  1159.      whether  the substitution operation should be done with or without any
  1160.      approval.
  1161.      
  1162.          If you decide to approve each change, then the editor  will  pause
  1163.      after  it  has  found a match. You are given the option to perform the
  1164.      change ('y'), to ignore the change ('n'), or to quit the  substitution
  1165.      operation ('q').
  1166.      
  1167.          In  the substitution text, you may use the metacharacter '&'. This
  1168.      means that you want to use the matched pattern as  part  of  the  sub-
  1169.      stitution text.
  1170.      
  1171.          For  example, let's say that you specified 'abc' as the pattern to
  1172.      search for. A substitution  text  of  '&xxx'  would  change  'abc'  to
  1173.      'abcxxx'.  Likewise,  a  substitution  text of '12 && 34' would change
  1174.      'abc' to '12 abcabc 34'. To use a '&' literally  in  the  substitution
  1175.      text, preceed the '&' by a backslash ('\').
  1176.      
  1177.          In  the substitution text, you may also refer to a tagged pattern.
  1178.      For example, let's say that the pattern that you searched for was :
  1179.        \(dog\) = \(cat\)
  1180.      If you want to replace every occurence of "dog = cat" by "cat =  dog",
  1181.      then the substitution pattern that you specify can be :
  1182.        \2 = \1
  1183.      What  this  says  is that you want the new substitution text to be the
  1184.      first matched pattern ("dog") followed by  "  =  ",  followed  by  the
  1185.      second matched pattern ("cat").
  1186.      
  1187.          To show a more powerful example, you can have the search pattern :
  1188.        \([a-z]+\)->prev = \([a-z]+\);
  1189.      and the substitution pattern :
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.      Searching and Substituting                      Chapter 7   Page 2
  1197.  
  1198.  
  1199.                                 ME USERS MANUAL
  1200.  
  1201.  
  1202.  
  1203.  
  1204.  
  1205.  
  1206.        \2->next = \1;
  1207.      The pattern will match a sequence of lower case letters,  followed  by
  1208.      "->next = ",  followed by another sequence of lower case letters, fol-
  1209.      lowed by a semi-colon. The first sequence of lower case  letters  that
  1210.      is  matched  is  tagged as "\1", and the second sequence of lower case
  1211.      letters is tagged as "\2". This would change the line
  1212.        currentline->prev = newline;
  1213.      to
  1214.        newline->next = currentline;
  1215.      
  1216.          If you need to search for any special control characters, then you
  1217.      can  use  the <QUOTE> (ALT Q) command. When you press the <QUOTE> key,
  1218.      the next character that you type will be  inserted  literally  in  the
  1219.      search string.
  1220.      
  1221.          Searches are normally sensitive to case (ie - upper and lower case
  1222.      letters are different). The <IGNORE CASE> command toggles a flag which
  1223.      allows searches to ignore the case of letters. The key associated with
  1224.      this command is <ALT> F5.
  1225.      
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.  
  1234.  
  1235.  
  1236.  
  1237.  
  1238.  
  1239.  
  1240.  
  1241.  
  1242.  
  1243.  
  1244.  
  1245.  
  1246.  
  1247.  
  1248.  
  1249.  
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.      Searching and Substituting                      Chapter 7   Page 3
  1260.  
  1261.  
  1262.                                ME USERS MANUAL
  1263.  
  1264.  
  1265.  
  1266.  
  1267.  
  1268.  
  1269.                                KEYBOARD MACROS
  1270.     
  1271.         The editor lets you save a sequence of keystrokes  that  you  type
  1272.     for  later  use.  This  is referred to as a "keystroke macro". You can
  1273.     have only one keystroke macro defined at a time.  (If  popular  demand
  1274.     warrants it, we will lift this restriction in future versions.) 
  1275.     
  1276.         Keystroke macros are useful if you must perform a tedious sequence
  1277.     of keystrokes over and over. The sequence is so simple that it may not
  1278.     be  worth  it  to write a macro program to do the task. If this is the
  1279.     case, invoke the <CAPTURE> command, type the  sequence  of  keystrokes
  1280.     once, and then press <CAPTURE> again. Your sequence of keystrokes will
  1281.     be saved, and can be replayed by pressing the <REPLAY> key. 
  1282.     
  1283.     
  1284.     <CAPTURE>                              <F4>
  1285.     
  1286.         This  function  starts  the  definition  of  a keyboard macro. All
  1287.     keystrokes that are typed are saved in memory  in  addition  to  being
  1288.     sent  to  the  editor.  Pressing  the <CAPTURE> key again will end the
  1289.     macro definition. See <REPLAY> to  see  how  to  recall  the  keyboard
  1290.     macro. 
  1291.     
  1292.     <REPLAY>                               <F3>
  1293.     
  1294.         This function replays a keyboard macro that was previously defined
  1295.     by the <CAPTURE> function. This command also takes an optional numeric
  1296.     argument, so that <ESC> 5 <REPLAY> will replay the keyboard macro five
  1297.     times. 
  1298.     
  1299.     
  1300.     <GENERATE MACRO>                       <SH> <F3>
  1301.     
  1302.         Occasionally, you may have a keystroke macro that you like so much
  1303.     that you will want to write a macro program which does the same thing.
  1304.     The <GENERATE MACRO> function prompts you for the name which you would
  1305.     like  to call this generated macro. You are also prompted for the file
  1306.     name which you would like to APPEND the generated macro to. The editor
  1307.     will  then  try  to  generate  a  macro function in the editor's macro
  1308.     programming language.
  1309.     
  1310.         The  generated macro will be APPENDED to the file you specify. The
  1311.     reason for this is because you might have a special macro  file  which
  1312.     you  like  to  save  these  little  gems  in.  You  should examine the
  1313.     generated macro to make sure that the editor generated the right code. 
  1314.     
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.     Keystroke Macros                                Chapter 8   Page 1
  1323.  
  1324.  
  1325.                                ME USERS MANUAL
  1326.  
  1327.  
  1328.  
  1329.  
  1330.  
  1331.  
  1332.                                 WINDOW COMMANDS
  1333.     
  1334.         A  "window"  is  a view into a buffer of text. Initially, you have
  1335.     one full-screen sized window into your file.  There  are  commands  to
  1336.     create and delete windows.
  1337.     
  1338.         Two  windows  can show different parts of the same buffer. This is
  1339.     useful if you have a long document, and you want to refer to one  part
  1340.     of  the  document  while editing another. Of course, different windows
  1341.     can contain different buffers.
  1342.     
  1343.         The editor allows you to have as many as 12 windows visible on the
  1344.     screen.  The  screen  is split horizontally for each of these windows,
  1345.     with each window being approximately the same size. 
  1346.     
  1347.         Many times, you would like to expand a window to take up the whole
  1348.     screen. There is a function to enlarge a window so that  it  takes  up
  1349.     the  whole screen, and to shrink a window back down and make the other
  1350.     windows visible. 
  1351.     
  1352.         You are allowed to transfer text between windows. The 10 pick buf-
  1353.     fers are common to all windows. Any text put into a pick buffer can be
  1354.     pasted into any window. 
  1355.     
  1356.     
  1357.     <SPLIT>                                <ALT> 2
  1358.     
  1359.         This functions adds another window to the screen. You can have  at
  1360.     most  12  windows.  Each  window  is  split  horizontally, and has ap-
  1361.     proximately the same number of lines. 
  1362.     
  1363.         You are prompted for the file name to read into  the  new  window.
  1364.     Type in the name, or press <RETURN> to have a copy of the current buf-
  1365.     fer inserted into the new window. 
  1366.     
  1367.     <CLOSE WINDOW>                         <ALT> 1 or <CTRL> D
  1368.     
  1369.         This function closes the current window (the window which the cur-
  1370.     sor is in). You are asked if you want to save the contents of the file
  1371.     in that window. 
  1372.     
  1373.     <ENLARGE WINDOW>                       <ALT> +
  1374.     
  1375.         This  function  allows you to expand the current window occupy the
  1376.     entire screen. If there are any other windows, they  will  remain  in-
  1377.     visible until the <SHRINK WINDOW> command is pressed. 
  1378.     
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.     Editing Multiple Files with Windows             Chpater 9   Page 1
  1386.  
  1387.  
  1388.                                ME USERS MANUAL
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.     <SHRINK WINDOW>                        <ALT> -
  1396.     
  1397.         This function makes all windows visible. This is used in  conjunc-
  1398.     tion with the <ENLARGE WINDOW> command. 
  1399.     
  1400.     <NEXT WINDOW>                          <PRTSC>
  1401.     
  1402.         This function moves the cursor to the next window on  the  screen,
  1403.     and makes that window the current window.
  1404.     
  1405.  
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424.  
  1425.  
  1426.  
  1427.  
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.     Editing Multiple Files with Windows             Chpater 9   Page 2
  1449.  
  1450.  
  1451.                                ME USERS MANUAL
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.                             MISCELLANEOUS COMMANDS
  1459.     
  1460.         The <MATCH BRACE> command will find a corresponding curly brace or
  1461.     parenthesis.  If  the cursor is on a left curly brace or a left paren-
  1462.     thesis, then the editor will search forward for a corresponding  right
  1463.     brace  or  right  paren.  If the cursor is on a right brace or a right
  1464.     paren, then the editor will search  backwards  for  the  corresponding
  1465.     left  brace  or  left paren. If the match is found, then the cursor is
  1466.     placed on the matched character. If no match is found, an  error  mes-
  1467.     sage will be given. 
  1468.     
  1469.         You  can set variable length tabs by using the <SET TABS> command.
  1470.     This command is invoked by the <ALT> T key. You will first be prompted
  1471.     to see if you want to clear the previously set tab stops.  Then,  type
  1472.     in the list of tab stops, each number separated by one or more blanks.
  1473.     For  instance, an assembly language programmer may want to set tabs at
  1474.     "10 16 23 35".
  1475.     
  1476.         The <REDRAW SCREEN> command (key <ALT> R) clears  the  screen  and
  1477.     draws  a new copy of the text on the screen. This is useful if you are
  1478.     not sure of what's on the screen, or if  funny  characters  appear  on
  1479.     your screen due to noise on communication lines. 
  1480.     
  1481.         If you have an Enhanced Graphics Adapter, the <TOGGLE EGA> command
  1482.     (CTRL E) will toggle you in and out of 43 line mode. 
  1483.     
  1484.         The <OPERATING SYSTEM> command (key <ALT> X) allows you to execute
  1485.     an  operating system command from within the editor. Type the command,
  1486.     followed by <RETURN>, and the command will be executed. After the com-
  1487.     mand is finished, you will be brought back to your editing screen.  In
  1488.     DOS, you can invoke a secondary command processor by typing "command".
  1489.     You  will  then  "leave" the word processor, and you can interact with
  1490.     DOS. When you want to return to the editing session, type the DOS com-
  1491.     mand "exit". 
  1492.     
  1493.         There  is  another interface to MS-DOS called <DOS CAPTURE>, which
  1494.     is invoked by hitting the <CTRL> X key. This  command  functions  like
  1495.     <OPERATING SYSTEM> command, except that a complete  log  of  your  DOS
  1496.     session  will  be kept. When you exit the command, the captured output
  1497.     will be put in another window. If you want to save this file, you must
  1498.     use the <WRITE FILE> command to save it to another file. (This is  be-
  1499.     cause  the temporary file that the session is saved in will be deleted
  1500.     automatically.) 
  1501.     
  1502.         The  <VERSION>  (key <ALT> V) command displays the current version
  1503.     number of the editor.
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.     Miscellaneous Commands                          Chapter 10  Page 1
  1512.  
  1513.  
  1514.                                ME USERS MANUAL
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.     
  1522.  
  1523.  
  1524.  
  1525.  
  1526.  
  1527.  
  1528.  
  1529.  
  1530.  
  1531.  
  1532.  
  1533.  
  1534.  
  1535.  
  1536.  
  1537.  
  1538.  
  1539.  
  1540.  
  1541.  
  1542.  
  1543.  
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.     Miscellaneous Commands                          Chapter 10  Page 2
  1575.  
  1576.  
  1577.                                ME USERS MANUAL
  1578.  
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.                                EDITOR VARIABLES
  1585.     
  1586.         There are several variables that are associated with  the  editor.
  1587.     These  variables  control some of the behavior of the editor during an
  1588.     editing session. By altering these values, you can  further  customize
  1589.     your editing session.
  1590.     
  1591.     
  1592.                             THE CONFIGURATION FILE
  1593.     
  1594.         Included  in the editor package is a file called "CONFIG.ME". This
  1595.     file contains a list of the editor variables and their default values.
  1596.     The meaning of each editor variable is explained below.
  1597.     
  1598.         When the editor starts up, it will  try  to  find  the "CONFIG.ME"
  1599.     file. The editor will first search your current directory, and if it's
  1600.     not  found  there, will search each directory in your DOS search path.
  1601.     If the file is still not found, then the editor will use its  built-in
  1602.     default values.
  1603.     
  1604.         There  are directions inside the "CONFIG.ME" file for altering the
  1605.     default values.
  1606.     
  1607.     
  1608.                     CHANGING THE VARIABLES FROM THE EDITOR
  1609.     
  1610.         You can alter any of the  editor  variables  during  your  editing
  1611.     session.  To do this, use the <OPTIONS> command. The default keystroke
  1612.     for this is <ALT> O.
  1613.     
  1614.         When you press the <OPTIONS> key, the screen  will  clear,  and  a
  1615.     list  of  editor variables will be shown. The name of each variable is
  1616.     shown, followed by its two-character code, followed by its  value.  To
  1617.     change  the  value of a variable, type the two-character code followed
  1618.     by a blank, followed by the value.
  1619.     
  1620.         As an example, let's say that you want to disable the auto  indent
  1621.     feature.  From  the options menu, locate the auto indent variable. You
  1622.     see that its two-letter code is "ai". Type "ai n", and  hit  <RETURN>.
  1623.     You will see that the auto indent variable has changed.
  1624.     
  1625.         To get back to the editing session, press either the <ESC> key  or
  1626.     the <CTRL> D key. The new values will take effect when you return from
  1627.     the  options menu. The changes remain in effect just until the editing
  1628.     session is over.
  1629.     
  1630.     
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.     Configuring the Editor                          Chapter 11  Page 1
  1638.  
  1639.  
  1640.                                ME USERS MANUAL
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.  
  1647.                              THE EDITOR VARIABLES
  1648.     
  1649.         Below is a list of the editor variables which are used to  control
  1650.     your  editing  session.  After  the  name  of  the  option  is the two
  1651.     character code which you use when you want to change an option.
  1652.     
  1653.     
  1654.         Horizontal Scroll (hs)
  1655.     
  1656.         This variable determines how many columns the screen  will  scroll
  1657.     leftwards  or  rightwards  when  horizontal  scrolling  is  performed.
  1658.     Horizontal scrolling will be initially performed when the cursor moves
  1659.     past the right edge of the current window. The default value  of  this
  1660.     variable is 40 columns.
  1661.     
  1662.         Vertical Scroll (vs)
  1663.     
  1664.         This parameter controls the number of lines the cursor moves  when
  1665.     the  <PGUP>  and <PGDN> key are pressed. When those two keys are pres-
  1666.     sed, then the value of the VS parameter will be  SUBTRACTED  from  the
  1667.     current  window  size. The result is the number of lines in the buffer
  1668.     that the cursor will move upwards or downwards. 
  1669.     
  1670.         As an example, if you want the cursor to move down only  20  lines
  1671.     when  the  <PGDN>  key  is  hit, then the VS parameter should have the
  1672.     value 4. In a full screen window, the cursor will move  (24  4)  =  20
  1673.     lines.  However, in a split screen window, the cursor will move (11-4)
  1674.     = 7 lines. 
  1675.     
  1676.     
  1677.     
  1678.     
  1679.         Foreground Color (fg)
  1680.         Background Color (bg)
  1681.     
  1682.         These variables determine the color of the characters (foreground)
  1683.     and the "spaces" (background). These variables only take effect if you
  1684.     have a color card in your PC.  Each  variable  can  take  on  a  Talue
  1685.     from  0 to 7. The colors are set according to the standard IBM PC con-
  1686.     ventions. Here is a table of the colors and their associated values :
  1687.     
  1688.       0  Black   (default for background color)
  1689.       1  Blue
  1690.       2  Green
  1691.       3  Cyan
  1692.       4  Yellow
  1693.       5  Magenta
  1694.  
  1695.  
  1696.  
  1697.  
  1698.  
  1699.  
  1700.     Configuring the Editor                          Chapter 11  Page 2
  1701.  
  1702.  
  1703.                                ME USERS MANUAL
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.       6  Brown
  1711.       7  White   (default for foreground color)
  1712.     
  1713.     
  1714.         Increment for tab stops (ta)
  1715.     
  1716.         Controls  the  distance between tab stops. The default value is 8,
  1717.     which means that tab stops will be set at columns 9, 17, 25, 33, etc.
  1718.     
  1719.     
  1720.         Filler for tabs  (tb)
  1721.     
  1722.         When  the <TAB> key is pressed, blank spaces will be inserted into
  1723.     the text until the cursor reaches the next tab stop. However,  instead
  1724.     of  blanks  being  inserted,  you can choose any character as the fill
  1725.     character. This variable takes the ASCII value of the character as its
  1726.     value. The default is the space character, which has ASCII value 32.
  1727.     
  1728.         Automatic Indentation (ai)
  1729.     
  1730.         When a new line is created (by hitting the  <RETURN>  key  or  the
  1731.     <INSERT LINE> key), you can specify whether or not the new line should
  1732.     be automatically indented. If this variable has a non-zero value, then
  1733.     the new line will be indented underneath the first non-blank character
  1734.     of  the  previous  line.  This  feature  is  especially convenient for
  1735.     programmers who like to indent their code after certain statements.
  1736.     
  1737.     
  1738.         Automatic backup (ab)
  1739.     
  1740.         To  help  prevent  losing your work in case of a system crash, the
  1741.     editor has an option to do automatic backups. If this  option  is  on,
  1742.     then the editor will write out the contents of the current buffer to a
  1743.     "filename.BK2"  file  periodically. See the option below to change the
  1744.     periodicity. If you finish your editing session successfully, then the
  1745.     backup file will be deleted.
  1746.     
  1747.         Please note that the "BK2" file is different than the ".BAK"  file
  1748.     that  the  editor  creates  when you save your work. The "BAK" file is
  1749.     just a copy of your old file before the  editing  session.  The  "BK2"
  1750.     file  is  a  "snapshot"  of  your  current  session  made  at periodic
  1751.     intervals.
  1752.     
  1753.         Create .BAK file (bk)
  1754.     
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.     Configuring the Editor                          Chapter 11  Page 3
  1764.  
  1765.  
  1766.                                ME USERS MANUAL
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.         If  this  option  is OFF, then the editor will NOT create a backup
  1774.     file if you save the current file. The only advantage of turning  this
  1775.     option  OFF  is that you won't clutter your disk with .BAK files. But,
  1776.     we have come to rely on the .BAK files on numerous ocassions.
  1777.     
  1778.         Keystrokes for automatic backup (sv)
  1779.     
  1780.         If the automatic backup feature is  enabled,  then  this  variable
  1781.     controls the period between saves, measured in keystrokes. The default
  1782.     is  to  do  an  automatic  backup  once every 1000 keystrokes. You can
  1783.     decrease this amount for more  reliability,  or  increase  it  if  the
  1784.     wait during the automatic backup is annoying.
  1785.     
  1786.         Sound Bell with Prompts (bl)
  1787.     
  1788.         If  this  parameter  is  on,  then  the  bell on the PC will sound
  1789.     whenever the editor prompts you for a command. The bell may be  annoy-
  1790.     ing  to  you,  depending  on  how late you're staying up to debug your
  1791.     program. 
  1792.     
  1793.         Insert Mode (in)
  1794.     
  1795.         This variable determined whether the editor will be in  insert  or
  1796.     overstrike  mode  when  the  editor  starts  up.  Give this variable a
  1797.     non-zero value if you want insert mode to be the default.
  1798.     
  1799.         Cursor can go into "Free Space" (fs)
  1800.     
  1801.         The  term "Free Space" refers to the area after the last character
  1802.     of a line. Some editors refuse to let you move the cursor past the end
  1803.     of a line; if you do, then the cursor  usually  jumps  to  either  the
  1804.     first  character of the next line, or the column immediately after the
  1805.     end of the line. If the Free Space variable is off,  then  the  editor
  1806.     will not let the cursor move into free space.
  1807.     
  1808.         If you type a character in free space, then the area from the last
  1809.     character  of  the  line  until the column where the cursor is will be
  1810.     filled with blanks.
  1811.     
  1812.         Prompt user for <PUT> option (pu)
  1813.     
  1814.         If  this  variable is OFF, and the text that is in the pick buffer
  1815.     was not put in there by a columnar block operation,  then  the  editor
  1816.     will  not prompt you when you <PUT> the text. (Key F9). Otherwise, the
  1817.     editor will ask you if you want to insert the text above  the  current
  1818.     line, push the text before the cursor position, or overlay the text.
  1819.     
  1820.  
  1821.  
  1822.  
  1823.  
  1824.  
  1825.  
  1826.     Configuring the Editor                          Chapter 11  Page 4
  1827.  
  1828.  
  1829.                                ME USERS MANUAL
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.         Wait for acknowledgement of an error (er)
  1837.     
  1838.         If  this  variable  is  ON,  then the user must hit a key after an
  1839.     error message is printed on the status line. If this variable is  OFF,
  1840.     then  the  error message will be printed, but the user can go right on
  1841.     typing commands.
  1842.     
  1843.         Strip high bits when reading a file (hb)
  1844.     
  1845.         Some  word  processors  use  a special encoding where they set the
  1846.     high bit ON on some of the characters. If this option is ON, then each
  1847.     character that is read in will have its high bit turned OFF. 
  1848.     
  1849.         Convert blanks to tabs (bt)
  1850.     
  1851.         In  order to save disk space, you may choose to compress sequences
  1852.     of blanks to tabs when the file is saved. The default value is OFF, so
  1853.     your output file will contain no tabs. 
  1854.     
  1855.         Snow on CGA? (ns)
  1856.     
  1857.         Many  Color  Graphics  Adapters require you to wait for horizontal
  1858.     retrace before writing a character to  the  screen.  However,  certain
  1859.     CGAs do not require the waiting period. If your CGA does not require a
  1860.     wait, turn this option OFF (ie - there is NO snow).
  1861.     
  1862.  
  1863.  
  1864.  
  1865.  
  1866.  
  1867.  
  1868.  
  1869.  
  1870.  
  1871.  
  1872.  
  1873.  
  1874.  
  1875.  
  1876.  
  1877.  
  1878.  
  1879.  
  1880.  
  1881.  
  1882.  
  1883.  
  1884.  
  1885.  
  1886.  
  1887.  
  1888.  
  1889.     Configuring the Editor                          Chapter 11  Page 5
  1890.  
  1891.  
  1892.                                ME USERS MANUAL
  1893.  
  1894.  
  1895.  
  1896.  
  1897.  
  1898.  
  1899.                               THE MACRO LANGUAGE
  1900.     
  1901.         Even   though  the  editor  is  a  very  powerful  tool  for  text
  1902.     manipulation, sometimes you find yourself wishing  for  commands  that
  1903.     the editor does not provide. Therefore, the editor provides a facility
  1904.     for  you to write your own editing commands. These commands are called
  1905.     "macros". 
  1906.     
  1907.         The  macro  language  that  the  editor  comes  with resembles the
  1908.     programming language called "C". Although the macro language is a  far
  1909.     cry from the complete C language, the syntax of the statements closely
  1910.     resembles that of C.
  1911.     
  1912.     
  1913.                               COMPILING A MACRO
  1914.     
  1915.         A macro file can contain several macros. The macro  file  must  be
  1916.     compiled with the macro compiler  (maccomp.exe).  If  the  compile  is
  1917.     successful,  then  the  compiled  macro  will be written out to a file
  1918.     with the same "root" name, but with the extension ".EXM". Then the ex-
  1919.     ecutable version of the macro (macro.exm) should be  loaded  into  the
  1920.     editor when you want to use it.
  1921.     
  1922.         To load a macro into the editor, you can
  1923.     
  1924.       1)  use the <ALT> P key and specify the name of the macro. This will
  1925.     load but NOT execute the macro. See below for  directions  on  how  to
  1926.     execute a macro.
  1927.     
  1928.       2)  use  the -l option on the command line, and give the name of the
  1929.     macro file after the "l". Example - "me -lisrch foo.c".
  1930.     
  1931.     
  1932.                               EXECUTING A MACRO
  1933.     
  1934.         In order to execute a macro, the macro must  be  loaded  into  the
  1935.     editor  by either one of the two methods mentioned above. Once a macro
  1936.     is loaded, you can press the <ALT> P key, and give  the  name  of  the
  1937.     macro to execute.
  1938.     
  1939.         Additionally,  you  can  make  any keystroke invoke a macro. To do
  1940.     this, use the <ASSIGN KEY> command (the ALT F4 key). You are asked for
  1941.     the name of the macro to invoke, and for the keystroke  which  invokes
  1942.     it.
  1943.     
  1944.  
  1945.  
  1946.  
  1947.  
  1948.  
  1949.  
  1950.  
  1951.  
  1952.     Introduction to the Macro Language              Chapter 12  Page 1
  1953.  
  1954.  
  1955.                                ME USERS MANUAL
  1956.  
  1957.  
  1958.  
  1959.  
  1960.  
  1961.  
  1962.         You  can  bind  a  keystroke  to a macro by using the assign_key()
  1963.     function in the macro. You should define the  key  assignment  in  the
  1964.     macro's init() procedure (see the end of this chapter).
  1965.     
  1966.     
  1967.                                   DATA TYPES
  1968.     
  1969.         The  macro  language supports two data types - integer and string.
  1970.     An integer is a whole number between -32,767 and +32,767. A string  is
  1971.     a sequence of 1 or more characters, ended by the NULL character (ASCII
  1972.     value 0).
  1973.     
  1974.         In the macro language, the word "int" is used to declare variables
  1975.     as  type  integer.  The  word  "string"  is  used  to  declare  string
  1976.     variables.  If  you  are a C programmer, be careful not to slip up and
  1977.     declare string variables as "char *".
  1978.     
  1979.     
  1980.                                   CONSTANTS
  1981.     
  1982.         An  integer  is  a  sequence  of  digits,  preceded by an optional
  1983.     negative sign.
  1984.     
  1985.         A single character can be referred to by enclosing  it  in  single
  1986.     quotes.   Characters  will  be  converted  internally  to  an  integer
  1987.     representing the ASCII value of the character. 
  1988.     
  1989.         You  can  represent   non-printable   characters   and   non-ASCII
  1990.     characters  by  enclosing  between  the  single  quotes  a  backslash,
  1991.     followed by  up  to  3  digits.  For  instance,  '\07'  represents the
  1992.     character CTRL-G (ASCII value 7), and '\233' represents the value 233.
  1993.     Notice that the written number is decimal (not octal).
  1994.     
  1995.         Several   popular   control  characters  can  be  expressed  by  a
  1996.     backslash, followed by a letter. Here is a list of those characters.
  1997.     
  1998.       '\b'  backspace
  1999.       '\n'  newline
  2000.       '\E'  escape
  2001.       '\''  single quote
  2002.       '\\'  backslash
  2003.     
  2004.         A string is a sequence of characters enclosed  in  double  quotes.
  2005.     Internally, each string is ended by an invisible NULL character (ASCII
  2006.     value  0). You do not have to write the NULL character - its prescence
  2007.     is implied by  the  definition  of  a  string.  However,  if  you  are
  2008.     examining the string by looking at a character at a time, you can test
  2009.     the current character to see if it's 0.
  2010.  
  2011.  
  2012.  
  2013.  
  2014.  
  2015.  
  2016.     Introduction to the Macro Language              Chapter 12  Page 2
  2017.  
  2018.  
  2019.                                ME USERS MANUAL
  2020.  
  2021.  
  2022.  
  2023.  
  2024.  
  2025.  
  2026.     
  2027.         Any  character  in the string can be one of the control characters
  2028.     mentioned above.
  2029.     
  2030.     
  2031.                                   OPERATORS
  2032.     
  2033.       Arithmetic operators
  2034.     
  2035.       +  addition
  2036.       -  subtraction or unary minus
  2037.       *  multiplication
  2038.       /  division
  2039.       %  modulo (remainder)
  2040.     
  2041.         As in most programming languages, multiplication and division take
  2042.     precedence over addition and subtraction.
  2043.     
  2044.        Auto increment and decrement are supported,  as  are  certain  aug-
  2045.     mented operators. You can have the constructs 
  2046.       
  2047.         ++x, x++, --x, x--
  2048.         x += y, x -= y, x *= y, x /= y, x %= y
  2049.     
  2050.       Relational operators
  2051.     
  2052.       <  less than
  2053.       <= less than or equal
  2054.       >  greater than
  2055.       >= greater than or equal
  2056.       == equal
  2057.       != not equal
  2058.     
  2059.         Relational operators have equal precedence. Relational expressions
  2060.     evaluate  to 1 if true and to 0 if false. The relational operators can
  2061.     be applied to both data types, integer and string. (Note to C program-
  2062.     mers - there is no  strcmp()  function  you  can  use  the  relational
  2063.     operators to compare strings). 
  2064.     
  2065.       Logical operators
  2066.     
  2067.       && and
  2068.       || or
  2069.       !  not
  2070.     
  2071.  
  2072.  
  2073.  
  2074.  
  2075.  
  2076.  
  2077.  
  2078.  
  2079.     Introduction to the Macro Language              Chapter 12  Page 3
  2080.  
  2081.  
  2082.                                ME USERS MANUAL
  2083.  
  2084.  
  2085.  
  2086.  
  2087.  
  2088.  
  2089.         NOT has the highest precedence, followed by AND, and then OR.
  2090.     
  2091.     
  2092.     
  2093.                                   CONVERSIONS
  2094.     
  2095.         While the macro program is executing, the interpreter will attempt
  2096.     to  perform  conversions  of  data types to prevent the macro programs
  2097.     from bombing.
  2098.     
  2099.     
  2100.                              COMPILER DIRECTIVES
  2101.     
  2102.         The macro compiler can accept the directives #define and #include.
  2103.     The  #define  resembles the #define directive used in the C prepreces-
  2104.     sor. The #define directive takes a word and  a  string  it  should  be
  2105.     replaced  by.  At  this point, you cannot have macro functions defined
  2106.     (ie you cannot have something like "#define sqr(x) ((x)*(x))" yet). 
  2107.     
  2108.       example of #define
  2109.     
  2110.     #define CTRL_C    3
  2111.     assign_key("center", CTRL_C);
  2112.     
  2113.         The macro language has an #include directive which allows  you  to
  2114.     include files for compilation. The syntax is : 
  2115.     
  2116.       #include filename
  2117.     
  2118.     As an example, 
  2119.     
  2120.       #include srchmark
  2121.     
  2122.     (Note - filename should NOT be in quotes NOR in angle brackets like in
  2123.     C).
  2124.     
  2125.     
  2126.     
  2127.                                  STATEMENTS
  2128.     
  2129.         Each  statement  must be ended by a semi-colon (';').  There is no 
  2130.     limit on the number of statements on one line,  or the column in which 
  2131.     a statement begins. The macro compiler is insensitive to white space.  
  2132.     
  2133.     LIST OF STATEMENTS
  2134.     
  2135.  
  2136.  
  2137.  
  2138.  
  2139.  
  2140.  
  2141.  
  2142.     Introduction to the Macro Language              Chapter 12  Page 4
  2143.  
  2144.  
  2145.                                ME USERS MANUAL
  2146.  
  2147.  
  2148.  
  2149.  
  2150.  
  2151.  
  2152.     Assignment
  2153.     
  2154.       variable = value;
  2155.     
  2156.         This statement is used to put a certain value into the variable on 
  2157.     the  left hand side of the '=' sign.  The value can be any expression, 
  2158.     which can be comprised of other variables, constants, and operators.  
  2159.     
  2160.         Examples :
  2161.     
  2162.       int n;
  2163.       string s;
  2164.     
  2165.       n = 3;
  2166.       n = n * 5 + strlen(str);
  2167.       s = "This is a message";
  2168.     
  2169.     
  2170.     If statement
  2171.     
  2172.       if (condition) 
  2173.         stmt;
  2174.     
  2175.       if (condition)
  2176.         stmt;
  2177.       else
  2178.         stmt;
  2179.     
  2180.         The condition inside the parentheses is evaluated, and tested  for
  2181.     a  non-zero value. If the result is non-zero, then the statement after
  2182.     the if (the "then" portion) will be executed. If the result was  zero,
  2183.     then the "else" portion will be executed.
  2184.     
  2185.         Each  'stmt'  can be a group of statements. This is often referred
  2186.     to as a "block statement". In this macro language, a  block  statement
  2187.     must  start  with  a  left curly brace ('{') and must end with a right
  2188.     curly brace ('}').
  2189.     
  2190.         As an example,
  2191.         
  2192.        if (x == 1)
  2193.        {
  2194.          y = 2 * y;
  2195.          insert(itoa(y));
  2196.        }
  2197.        else
  2198.        {
  2199.  
  2200.  
  2201.  
  2202.  
  2203.  
  2204.  
  2205.     Introduction to the Macro Language              Chapter 12  Page 5
  2206.  
  2207.  
  2208.                                ME USERS MANUAL
  2209.  
  2210.  
  2211.  
  2212.  
  2213.  
  2214.  
  2215.          x = x - 1;
  2216.          y = 3;
  2217.        }
  2218.     
  2219.         The curly braces may occur on the same line as the  "if"  and  the
  2220.     "else" parts. The style of indenting is up to you.
  2221.     
  2222.     
  2223.     While statement
  2224.     
  2225.       while (condition)
  2226.         stmt;
  2227.     
  2228.         The statement inside the 'while' will be executed continuously un-
  2229.     til the condition is found to be zero. 
  2230.     
  2231.         Example :
  2232.     
  2233.       while (!is_eol())
  2234.       {
  2235.         if (currchar() == 'x')
  2236.           delchar();
  2237.         else
  2238.           right();
  2239.       }
  2240.     
  2241.     
  2242.     For statement
  2243.     
  2244.       for (initial statement;  condition;  increment)
  2245.         stmt;
  2246.     
  2247.         This is equivalent to
  2248.     
  2249.       initial statement;
  2250.       while (condition)
  2251.       {
  2252.         stmt;
  2253.         increment;
  2254.       }
  2255.     
  2256.         The for statement is a more convenient way to do looping than  the 
  2257.     while  statement  if  the  loop  involves  counting  from one value to 
  2258.     another.  
  2259.     
  2260.     
  2261.  
  2262.  
  2263.  
  2264.  
  2265.  
  2266.  
  2267.  
  2268.     Introduction to the Macro Language              Chapter 12  Page 6
  2269.  
  2270.  
  2271.                                ME USERS MANUAL
  2272.  
  2273.  
  2274.  
  2275.  
  2276.  
  2277.  
  2278.     Break statement
  2279.     
  2280.       break;
  2281.     
  2282.         The break statement is used to exit from the inner most loop. If 
  2283.     there is only one loop, then the loop is exited.
  2284.     
  2285.         Example
  2286.     
  2287.           while (x < 13)
  2288.           {
  2289.              ....
  2290.              for (i = 1;  i <= len;  i = i + 1)
  2291.              {
  2292.                 ......
  2293.                 if (x < 0)
  2294.                   break;      /* go to the "x = x+1" statement */
  2295.                 ......
  2296.              }
  2297.              x = x + 1;
  2298.           } 
  2299.     
  2300.     
  2301.     Function calls
  2302.     
  2303.       function_name ([arg1, arg2, ..., argn]);
  2304.     
  2305.         You  can  call  any primitive function, any built-in macro, or any
  2306.     macro which you define. The calling function can pass arguments to the
  2307.     called routine. Each argument in the argument list  is  an  expression
  2308.     which  is evaluated, and then whose result is passed down to the call-
  2309.     ing routines. Arguments are passed by value, not by reference. 
  2310.     
  2311.         Examples :
  2312.     
  2313.         justify_line();
  2314.     
  2315.         if (is_string_numeric(str))
  2316.           ......
  2317.     
  2318.         n = strlen(str1) + strlen(n2);
  2319.     
  2320.     
  2321.     Return statement
  2322.     
  2323.  
  2324.  
  2325.  
  2326.  
  2327.  
  2328.  
  2329.  
  2330.  
  2331.     Introduction to the Macro Language              Chapter 12  Page 7
  2332.  
  2333.  
  2334.                                ME USERS MANUAL
  2335.  
  2336.  
  2337.  
  2338.  
  2339.  
  2340.  
  2341.       return;
  2342.       return expression;
  2343.     
  2344.         A return statement is used to terminate a macro and return to  the 
  2345.     calling macro, if any. An optional value may be returned by the macro.  
  2346.     The  return  expression  may be of type integer or type string.  Since 
  2347.     there is no type associated with a macro,  one  return  statement  may 
  2348.     return a string while another may return an integer.  
  2349.     
  2350.     
  2351.                                    COMMENTS
  2352.     
  2353.         Any  text  that  falls  between  "/*" (comment begin sequence) and
  2354.     "*/" (comment end sequence) will be ignored by the macro compiler, and
  2355.     will be treated as a comment. A comment may be placed on a line by it-
  2356.     self,  or  may  be  placed  after a statement. A comment can also span
  2357.     several lines.
  2358.     
  2359.     
  2360.                           THE LAYOUT OF A MACRO FILE
  2361.     
  2362.         A macro file looks like this :
  2363.     
  2364.       [optional global variable declarations]
  2365.     
  2366.       macro1 defintion
  2367.     
  2368.       [optional globals - seen only by macros 2-n]
  2369.     
  2370.       macro2 defintion
  2371.     
  2372.       ................
  2373.     
  2374.       macro n definition
  2375.     
  2376.     
  2377.                                GLOBAL VARIABLES
  2378.     
  2379.         Any global variables that you use should be declared at the top of
  2380.     the  macro  file.  These variables may be accessed by any macro in the
  2381.     macro file. 
  2382.     
  2383.         You can also declare globals in between two macro definitions  (ie 
  2384.     -  after  the  right  curly  brace  which ends a macro).  These global 
  2385.     definitions are only seen by the macros which  come  physically  AFTER
  2386.     these globals in the file. 
  2387.     
  2388.     
  2389.  
  2390.  
  2391.  
  2392.  
  2393.  
  2394.  
  2395.     Introduction to the Macro Language              Chapter 12  Page 8
  2396.  
  2397.  
  2398.                                ME USERS MANUAL
  2399.  
  2400.  
  2401.  
  2402.  
  2403.  
  2404.  
  2405.                                LOCAL VARIABLES
  2406.     
  2407.         Local variables are variables which can only be  used  within  the
  2408.     macro  which  they are declared in. These include the parameters which
  2409.     are passed to a macro. 
  2410.     
  2411.         If a variable is used inside a macro, and has not  been  declared,
  2412.     then the macro interpreter will declare  it  automatically,  and  will
  2413.     try  to  determine  its data type from the context in which it's used.
  2414.     The default type is integer. 
  2415.     
  2416.     
  2417.                               DEFINING A MACRO
  2418.     
  2419.         There can be as multiple macros defined in one  macro  file.  Each
  2420.     macro definition has the following form : 
  2421.     
  2422.       macro-name ([parameters])
  2423.         [parameter declarations]
  2424.       {
  2425.         [local variable declarations]
  2426.     
  2427.         statements
  2428.       }
  2429.     
  2430.         The first line is a header that contains the name  of  the  macro,
  2431.     and  an  optional list of parameters. The macro name must start with a
  2432.     letter or an underscore ('_'). The parentheses must follow  the  macro
  2433.     name, even if there are no parameters.
  2434.     
  2435.         If  the  macro  has  parameters,  then  the parameter declarations
  2436.     should follow. The  declarations  give  the  type  and  name  of  each
  2437.     parameter.  The  parameters  can  either  be  integer  or string. If a
  2438.     declaration for a parameter is left out, then the parameter is assumed
  2439.     to be of type integer.
  2440.     
  2441.         After the optional parameter declarations, a left curly brace must
  2442.     follow. Any local variables that the macro  uses  should  be  declared
  2443.     now.  Then  comes  the list of statement that comprise the body of the
  2444.     macro. The right curly brace ends the entire macro.
  2445.     
  2446.         If  you  are a C programmer, you may be used to declaring the type
  2447.     of the function, whether it be  an  integer  function  or  a  function
  2448.     returning  a  pointer.  In  this  macro  language,  there  are no type
  2449.     declarations associated with macros. The type of value  that  a  macro
  2450.     returns (if any) is determined by the RETURN statement.
  2451.     
  2452.  
  2453.  
  2454.  
  2455.  
  2456.  
  2457.  
  2458.     Introduction to the Macro Language              Chapter 12  Page 9
  2459.  
  2460.  
  2461.                                ME USERS MANUAL
  2462.  
  2463.  
  2464.  
  2465.  
  2466.  
  2467.  
  2468.         As  a  detailed example of a macro, let's consider writing a macro
  2469.     that  determines  if  a  string  contains all digits. The name of this
  2470.     macro will be "is_string_numeric". This macro, which should be  called
  2471.     by  another  macro,  takes one parameter - the string to examine. This
  2472.     macro should return 1 if the string is all numeric, and 0 if not.
  2473.     
  2474.         A loop is used to traverse the string, one character at a time. To
  2475.     extract the character  at  the  ith  position,  we  use  the  built-in
  2476.     function  substr().  The first argument to substr() is the name of the
  2477.     string to examine, the second argument is  the  starting  position  to
  2478.     look  at,  and  the  thrid  argument  is  the  number of characters to
  2479.     extract. Substr() returns a string result.
  2480.     
  2481.         The character is then tested to see if it falls outside the  range
  2482.     of  "0"  to  "9".  If  it  does,  then  that  means that a non-numeric
  2483.     character was found, and 0 is returned.
  2484.     
  2485.         If the loop ends, that means that all the characters were numeric.
  2486.     The second return statement is executed, and  1  is  returned  to  the
  2487.     calling macro.
  2488.     
  2489.     
  2490.     is_string_numeric(str)         /* macro definition */
  2491.       string str;                  /* parameters */
  2492.     {
  2493.       string  c;                   /* local variables */
  2494.       int  i, len;
  2495.     
  2496.       len = strlen(str);         /* get the number of characters in str */
  2497.     
  2498.       /* The for loop is used to walk through the string, one character at
  2499.        * a time. Notice that the  ith  character  of  a  string  occurs  at
  2500.        * position i. (Not at position i-1, like in C.) */
  2501.     
  2502.       for (i = 1;  i <= len;  i = i + 1)
  2503.       {
  2504.         c = substr(str, i, 1);     /* c is the character at position i */
  2505.         if (c < "0" || c > "9")    /* test if c is not numeric */
  2506.           return(0);               /* NO!!! */
  2507.       }
  2508.     
  2509.       return(1);    /* A positive return value means that it's numeric */
  2510.     }
  2511.     
  2512.     
  2513.  
  2514.  
  2515.  
  2516.  
  2517.  
  2518.  
  2519.  
  2520.  
  2521.     Introduction to the Macro Language              Chapter 12  Page 10
  2522.  
  2523.  
  2524.                                ME USERS MANUAL
  2525.  
  2526.  
  2527.  
  2528.  
  2529.  
  2530.  
  2531.                                THE INIT() MACRO
  2532.     
  2533.         When a macro file is loaded into the editor for the first time (by
  2534.     the  <LOAD  MACRO>  command  or by the -lmacname option on the command
  2535.     line), the editor looks for a macro called init(). If  this  macro  is
  2536.     defined  in  the  macro  file, then the editor will execute this macro
  2537.     once and only once when the macro file is first loaded.
  2538.     
  2539.         The kind of things that you might put in the init() macro would be
  2540.     key  assignments,  opening  messages,  and  initialization  of  global
  2541.     variables.  See  the  assign_key() primitive for information on how to
  2542.     make key assignments.
  2543.  
  2544.  
  2545.  
  2546.  
  2547.  
  2548.  
  2549.  
  2550.  
  2551.  
  2552.  
  2553.  
  2554.  
  2555.  
  2556.  
  2557.  
  2558.  
  2559.  
  2560.  
  2561.  
  2562.  
  2563.  
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.  
  2579.  
  2580.  
  2581.  
  2582.  
  2583.  
  2584.     Introduction to the Macro Language              Chapter 12  Page 11
  2585.  
  2586.  
  2587.                                 ME USERS MANUAL
  2588.  
  2589.  
  2590.  
  2591.  
  2592.  
  2593.  
  2594.                               THE EDITOR COMMANDS
  2595.      
  2596.          The  editor  functions  are  available  as a keystroke and/or as a
  2597.      function which can be called from a macro program.  In  the  following
  2598.      list  of  commands,  the  function name (if there is one) is specified
  2599.      first, and the default keystroke (if there is one) is specified  next.
  2600.      The keystroke name is enclosed between "<" and ">".
  2601.      
  2602.          A normal function key is designated as <F1-10>, a shifted function
  2603.      key  is  designated at <SH> <F1-10>, a CTRL function key is designated
  2604.      as <CTRL> <F1-10>, and an ALT function  key  is  designated  as  <ALT>
  2605.      <F1-10>.
  2606.      
  2607.      
  2608.                                NUMERIC ARGUMENTS
  2609.      
  2610.          Various  commands  can  take  an  optional  numeric argument. This
  2611.      number specified the number of  times  to  perform  that  command.  To
  2612.      specify  a  numeric  argument,  type the <ESCAPE> key, followed by the
  2613.      number, followed directly by the command key. (Do not type a  <RETURN>
  2614.      after the last digit of the number!)
  2615.      
  2616.      
  2617.                            CURSOR MOVEMENT COMMANDS
  2618.      
  2619.      up()                                   <UP ARROW>
  2620.      
  2621.      This  function  moves  the  cursor  up  one line. If the "GOFREESPACE"
  2622.      parameter is zero, and the cursor lands past the end of the new  line,
  2623.      then  the  cursor will be moved to just past the last character of the
  2624.      line. Up() returns 1 if the move was successful, and 0 if not. 
  2625.      
  2626.      down()                                 <DOWN ARROW>
  2627.      
  2628.      This function moves the cursor down one  line.  If  the  "GOFREESPACE"
  2629.      parameter  is  zero,  and the cursor is past the end of the line, then
  2630.      the cursor will be moved to just past the last character of the  line.
  2631.      Down() returns 1 if the move was successful, and 0 if not. 
  2632.      
  2633.      left()                                 <LEFT ARROW>
  2634.      
  2635.      This function moves the cursor left one character. If the cursor is at
  2636.      the  beginning  of  a line, then the cursor will move to just past the
  2637.      last character of the previous line. Left() returns 1  if  successful,
  2638.      and 0 if not. 
  2639.      
  2640.  
  2641.  
  2642.  
  2643.  
  2644.  
  2645.  
  2646.  
  2647.      Macro Functions - Editor Services               Chapter 13  Page 1
  2648.  
  2649.  
  2650.                                 ME USERS MANUAL
  2651.  
  2652.  
  2653.  
  2654.  
  2655.  
  2656.  
  2657.      right()                                <RIGHT ARROW>
  2658.      
  2659.      This  function moves the cursor right one column. If the "GOFREESPACE"
  2660.      parameter is zero, and the cursor is past the end of  the  line,  then
  2661.      the  cursor  will  be  moved  to the first character of the next line.
  2662.      Right() returns 1 if the move was successful, and 0 if not. 
  2663.      
  2664.      nextword()                             <CTRL> <RIGHT ARROW>
  2665.      
  2666.      This  function  moves  the  cursor  to  the  next word in the file. If
  2667.      successful, nextword() returns 1, else returns 0.
  2668.      
  2669.      prevword()                             <CTRL> <LEFT ARROW>
  2670.      
  2671.      This function moves the cursor to the previous word in  the  file.  If
  2672.      successful, prevword() returns 1, else returns 0.
  2673.      
  2674.      nextpara()                             <CTRL> <PGDN>
  2675.      
  2676.      This function moves the cursor to the next paragraph in the  file.  If
  2677.      successful,  nextpara()  returns  1,  else  returns  0. A paragraph is
  2678.      defined as the first line after one or more blank lines. The cursor is
  2679.      positioned at the first non-blank character of the new paragraph.
  2680.      
  2681.      prevpara()                             <CTRL> <PGUP>
  2682.      
  2683.      This  function moves the cursor to the previous paragraph in the file.
  2684.      If successful, prevpara() returns 1, else returns  0.  The  cursor  is
  2685.      positioned on the first non-blank character of the new paragraph.
  2686.      
  2687.      goline(n)                              <ALT> G
  2688.        int  n;   # the line number to go to
  2689.      
  2690.      Goline() allows you to jump to any line in the file. When this command
  2691.      is  invoked  from  the  keyboard, you are allowed to enter an absolute
  2692.      line number (3, 421), an amount relative to  the  current  line  (-23,
  2693.      +4),  or  an amount relative to the last line in the file ($, $-9). If
  2694.      you enter the letter 'a' through 'z', then the corresponding  bookmark
  2695.      will be jumped to (see bookmark()).
  2696.      
  2697.      gobof()                                <SH> <PGUP>
  2698.      
  2699.      This function moves the cursor to the first line of the file.
  2700.      
  2701.      gobol()                                <HOME>
  2702.      
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.      Macro Functions - Editor Services               Chapter 13  Page 2
  2711.  
  2712.  
  2713.                                 ME USERS MANUAL
  2714.  
  2715.  
  2716.  
  2717.  
  2718.  
  2719.  
  2720.      This function moves the cursor to column 1 on the current line.
  2721.      
  2722.      goeol()                                <END>
  2723.      
  2724.      This function moves the cursor to one column beyond the last character
  2725.      in the current line.
  2726.      
  2727.      goeof()                                <SH> <PGDN>
  2728.      
  2729.      This function moves the cursor to just after the last character of the
  2730.      file. 
  2731.      
  2732.      nextscreen()                           <PGDN>
  2733.      
  2734.      This  function  scrolls the current window down by the number of lines
  2735.      in the window.
  2736.      
  2737.      prevscreen()                           <PGUP>
  2738.      
  2739.      This function scrolls the current window up by the number of lines  in
  2740.      the window. 
  2741.      
  2742.      home()                                 <CTRL> <HOME>
  2743.      
  2744.      This function moves the cursor to the top left corner of  the  current
  2745.      window.
  2746.      
  2747.      bottom()                               <CTRL> <END>
  2748.      
  2749.      This function moves the cursor to the lower left corner of the current
  2750.      window.
  2751.      
  2752.      
  2753.                                DELETION COMMANDS
  2754.      
  2755.      backspace()                            <BACKSPACE>
  2756.      
  2757.      This  function deletes the character to the left of the cursor. If the
  2758.      cursor is at the beginning of a line, then the current  line  will  be
  2759.      joined to the end of the previous line. 
  2760.      
  2761.      
  2762.      delchar()                              <DEL>
  2763.      
  2764.      This function deletes the character under the cursor. If the cursor is 
  2765.      past the last character of the line, then the next line is joined with 
  2766.      the current line.
  2767.      
  2768.  
  2769.  
  2770.  
  2771.  
  2772.  
  2773.  
  2774.      Macro Functions - Editor Services               Chapter 13  Page 3
  2775.  
  2776.  
  2777.                                 ME USERS MANUAL
  2778.  
  2779.  
  2780.  
  2781.  
  2782.  
  2783.  
  2784.      deleol()                               <SH> <NUMERIC 5>
  2785.      
  2786.      This function deletes all characters from the current cursor  position
  2787.      until the end of the current line. 
  2788.        
  2789.      delline()                              <F1>
  2790.      
  2791.      This  function deletes the current line. It may be preceeded by a com-
  2792.      mand  count.  However,  if  the  editor  sees  that  there  are marked
  2793.      lines, then delline() will be performed on the marked lines.
  2794.      
  2795.      
  2796.      delword()                              <SH> <DEL>
  2797.      
  2798.      This function deletes the next word. If the cursor is in the middle of
  2799.      a word, then the whole word is still deleted. 
  2800.      
  2801.      
  2802.                               INSERTION COMMANDS
  2803.      
  2804.      <INS>
  2805.      
  2806.      This  keystroke  toggles  the editor between insert mode and overwrite
  2807.      mode. When insert mode is enabled, then a character that you type will
  2808.      push the remaining characters on the line over  by  one  column.  When
  2809.      overwrite  mode  is  on, then the character that you type will replace
  2810.      the old character at the cursor position.
  2811.      
  2812.      On the status line, the mode is indicated by an 'I'  for  insert  mode
  2813.      and an 'O' for overwrite mode. Also, the cursor is a full  block  when
  2814.      in insert mode, and an underscore when in overwrite mode.
  2815.      
  2816.      Insert mode is always on when a macro program is being executed.
  2817.      
  2818.      
  2819.      insline()                              <F2>
  2820.      
  2821.      This function inserts a blank line before the current line.
  2822.      
  2823.      
  2824.                             CUT AND PASTE COMMANDS
  2825.      
  2826.          The first three commands deal with only the current  line  (unless
  2827.      preceeded  by  the  optional numeric argument). However, if the editor
  2828.      sees that  there  are  marked  lines,  then  these  commands  will  be
  2829.      performed on the marked lines.
  2830.      
  2831.  
  2832.  
  2833.  
  2834.  
  2835.  
  2836.  
  2837.      Macro Functions - Editor Services               Chapter 13  Page 4
  2838.  
  2839.  
  2840.                                 ME USERS MANUAL
  2841.  
  2842.  
  2843.  
  2844.  
  2845.  
  2846.  
  2847.      cut()                                  <F8>
  2848.      
  2849.      This functions clears the current pick buffer, then copies the current
  2850.      line into it. The current line is then deleted. This function can take
  2851.      an optional numeric argument.
  2852.      
  2853.      cut_append()                           <SH> <F8>
  2854.      
  2855.      This  function  performs  the same operation as above, except that the
  2856.      current pick buffer is NOT cleared first. The  current  line  will  be
  2857.      appended onto the end of the pick buffer.
  2858.      
  2859.      copy()                                 <SH> <F9>
  2860.      
  2861.      This  function  copies  the current line into the current pick buffer.
  2862.      Copy() can take an optional numeric argument. 
  2863.      
  2864.      paste()                                <F9>
  2865.      
  2866.      This function inserts the lines contained in the current  pick  buffer
  2867.      above the current line. If the inserted lines start at whatever column
  2868.      the cursor is currently at.
  2869.      This function can take a numeric argument.
  2870.      
  2871.      
  2872.                                 BLOCK COMMANDS  
  2873.      
  2874.      
  2875.      mark()                                 <F7>
  2876.      
  2877.      This function places a mark at the cursor location.  If  this  is  the
  2878.      first time the marker was set for this block, nothing happens. If this
  2879.      is the second time, the block will be highlighted. 
  2880.      
  2881.      
  2882.      colmark()                              <SH> <F7>
  2883.      
  2884.      This function places a columnar mark at the cursor location. When this
  2885.      mark is set for the second time, then a rectangular region is defined.
  2886.      The top left and bottom right corners are defined by the two marks. 
  2887.      
  2888.      
  2889.      markline()                             <ALT> <F7>
  2890.      
  2891.      This  function  will mark the current line. You can mark any number of
  2892.      lines, and the series of lines which are marked  can  be  disjoint  or
  2893.      contiguous.  If  the  editor  detects  that lines are marked, then the
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.  
  2900.      Macro Functions - Editor Services               Chapter 13  Page 5
  2901.  
  2902.  
  2903.                                 ME USERS MANUAL
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.  
  2910.      delline(), cut(), cut_append(), copy(), and write_pick() commands work
  2911.      on the marked lines instead of the current line.
  2912.      
  2913.      
  2914.      markgroup()                            <ALT> <F8>
  2915.      
  2916.      This function searches backwards for the last line  that  was  marked,
  2917.      and  marks  all lines from the currentline until the last marked line.
  2918.      If no marked lines are found, then the current line is marked.
  2919.      
  2920.      
  2921.      clear_mark()                           <CTRL> <F8>
  2922.      
  2923.      This function clears out any marks, if any exists. This works on  both
  2924.      block marks and line marks.
  2925.      
  2926.      
  2927.      set_picknum(n)                         <CTRL> <F7>
  2928.        int n;
  2929.      
  2930.      Changes the current pick buffer to the number  you  choose.  The  pick
  2931.      buffers are numbered from 0 to 9, with buffer 0 as the default.
  2932.      
  2933.      
  2934.                          SEARCH & SUBSTITUTE COMMANDS
  2935.      
  2936.      fsearch(pattern)                       <F5>
  2937.        string pattern;
  2938.      
  2939.      Searches  through  the  buffer  for  the regular expression "pattern".
  2940.      The pattern may be any regular expression. If found, then the  current
  2941.      line  is set to the line that contains the first match, and the cursor
  2942.      is positioned at the match. Search() returns the column number of  the
  2943.      match (greater than 0) if it succeeds, and 0 if it doesn't. 
  2944.      
  2945.      rsearch(pattern)                       <SH> <F5>
  2946.        string pattern;
  2947.        
  2948.      This  function  is  similar to the fsearch() function, except that the
  2949.      file is searched backwards starting from the previous line.
  2950.      
  2951.      fsubst(pattern, subtext, approval)     <F6>
  2952.        string pattern, subtext;
  2953.        int    approval;
  2954.      
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.      Macro Functions - Editor Services               Chapter 13  Page 6
  2964.  
  2965.  
  2966.                                 ME USERS MANUAL
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.      This function  searches  for  the  first  occurence  of  pattern,  and
  2974.      substitutes  subtext  in  its  place.  The direction for the search is
  2975.      forwards. 'Approval' should be 0 if the substitution should be global,
  2976.      or non-zero if you want the user to approve each change.
  2977.      Fsubst() returns 1 if successful, and 0 if not.
  2978.      
  2979.      rsubst(pattern, subtext, approval)     <SH> <F6>
  2980.        string pattern, subtext;
  2981.        int    approval;
  2982.       
  2983.      Rsubst() is similar to fsubst(), except the direction for  the  search
  2984.      is backwards through the file.
  2985.      
  2986.      ignore_case(value)                     <ALT> <F5>
  2987.        int value;
  2988.      
  2989.      Allows  you  to  toggle  the  case-ignore  flag.  When  executing this
  2990.      function  from  a macro, it will SET the case-ignore flag if the value
  2991.      parameter is 1. Otherwise, it will RESET the flag.
  2992.      
  2993.      
  2994.                              INPUT/OUTPUT COMMANDS
  2995.      
  2996.      readfile(filename)                     <SH> <F10>
  2997.        string filename;
  2998.      
  2999.      This function reads the file "filename" into  the  buffer  BEFORE  the
  3000.      current  line. Returns 1 if successful, and 0 if not. The filename may
  3001.      be a full path name, including drive designator. 
  3002.      
  3003.      writefile(filename)                    <F10>
  3004.        string filename;
  3005.      
  3006.      This  function  write  the  current  buffer  out  to  the  file  named
  3007.      "filename".  Returns  1 if successful, 0 if not. The filename may be a
  3008.      full path name, including drive designator. 
  3009.      
  3010.      writepick(filename)                    <ALT> W
  3011.        string filename;
  3012.      
  3013.      This  function  write  the  contents of the current pick buffer to the
  3014.      named  file.  If there are marked lines, then the marked lines will be
  3015.      written to the named file.
  3016.      
  3017.      
  3018.  
  3019.  
  3020.  
  3021.  
  3022.  
  3023.  
  3024.  
  3025.  
  3026.      Macro Functions - Editor Services               Chapter 13  Page 7
  3027.  
  3028.  
  3029.                                 ME USERS MANUAL
  3030.  
  3031.  
  3032.  
  3033.  
  3034.  
  3035.  
  3036.                                 WINDOW COMMANDS
  3037.      
  3038.      The editor allows you to have as many as 6 windows visible on the 
  3039.      screen. The screen is split horizontally for each of these windows, 
  3040.      with each window being approximately the same size.
  3041.      
  3042.      Many times, you would like to expand a window to take up the whole 
  3043.      screen. There is a function to enlarge a window so that it takes up 
  3044.      the whole screen, and to shrink a window back down and make the other 
  3045.      windows visible.
  3046.      
  3047.      You are allowed to transfer text between windows. The 10 pick buffers 
  3048.      are common to all windows. Any text put into a pick buffer can be 
  3049.      pasted into any window.
  3050.      
  3051.      
  3052.      <SPLIT>                                <ALT> 2
  3053.      
  3054.      This functions adds another window to the screen. You can have at most six
  3055.      windows. Each window is split horizontally, and has approximately the same
  3056.      number of lines.
  3057.      
  3058.      You are prompted for the file name to read into the new window. Type in
  3059.      the name, or press <RETURN> to have a copy of the current window inserted
  3060.      into the new window.
  3061.      
  3062.      <CLOSE WINDOW>                         <ALT> 1 or <CTRL> D
  3063.      
  3064.      This function closes the current window (the window which the cursor is in).
  3065.      You are asked if you want to save the contents of the file in that window.
  3066.      
  3067.      <ENLARGE WINDOW>                       <ALT> +
  3068.      
  3069.      This function allows you to make the current window occupy the entire screen.
  3070.      If there are any other windows, they will remain invisible until the
  3071.      <SHRINK WINDOW> command is pressed.
  3072.      
  3073.      <SHRINK WINDOW>                        <ALT> -
  3074.      
  3075.      This function makes all windows visible. This is used in conjunction with
  3076.      the <ENLARGE WINDOW> command.
  3077.      
  3078.      <NEXT WINDOW>                          <PRTSC>
  3079.      
  3080.      This function makes the next window the current window, and moves the
  3081.      cursor there.
  3082.      
  3083.      
  3084.  
  3085.  
  3086.  
  3087.  
  3088.  
  3089.  
  3090.      Macro Functions - Editor Services               Chapter 13  Page 8
  3091.  
  3092.  
  3093.                                 ME USERS MANUAL
  3094.  
  3095.  
  3096.  
  3097.  
  3098.  
  3099.  
  3100.                                KEYBOARD MACROS
  3101.      
  3102.      <CAPTURE>                              <F4>
  3103.      
  3104.      This   function  starts  the  definition  of  a  keyboard  macro.  All
  3105.      keystrokes that are typed are saved in memory, in  addition  to  being
  3106.      sent  to  the  editor.  Pressing  the <CAPTURE> key again will end the
  3107.      macro definition. See <REPLAY> to  see  how  to  recall  the  keyboard
  3108.      macro. 
  3109.      
  3110.      <REPLAY>                               <F3>
  3111.      
  3112.      This function replays a keyboard macro that was previously defined by the
  3113.      <CAPTURE> function. This command also takes an optional numeric argument,
  3114.      so that <ESC> 5 <REPLAY> will replay the keyboard macro five times.
  3115.      
  3116.      
  3117.                                 MACRO PROGRAMS
  3118.      
  3119.          When  typed from the keyboard, <ALT> P will prompt you for a macro
  3120.      name. If the macro is not already loaded, then the name  you  type  is
  3121.      considered  to be an executable ".exm" file. The editor will load, but
  3122.      not execute that macro. On the other hand, if the editor detects  that
  3123.      the  macro  is  loaded, then it will execute that macro. In this case,
  3124.      <ALT> P may be preceeded by an optional numeric argument.
  3125.      
  3126.      loadmacro(macrofile)                   <ALT> P
  3127.        string macrofile;
  3128.      
  3129.      This function loads the macro file "macrofile" into the editor. There 
  3130.      must be an executable version of  the  macro  called  "macrofile.exm".
  3131.      Returns 1 if the loading succeeded, and 0 if not.
  3132.      
  3133.      domacro(macroname)                     <ALT> P
  3134.        string macroname;
  3135.      
  3136.      This function executes the (previously loaded) macro named "macroname".
  3137.      
  3138.      
  3139.                             MISCELLANEOUS COMMANDS
  3140.      
  3141.      <QUOTE>                                <ALT> Q
  3142.      
  3143.      This  allows  you  to  insert a control character into the text at the
  3144.      cursor location. A control character is defined as a  character  whose
  3145.      ASCII  value  is less than 32 or greater than 126. On the IBM PC, this
  3146.      character will usually be represented as a graphic symbol. 
  3147.      
  3148.  
  3149.  
  3150.  
  3151.  
  3152.  
  3153.  
  3154.      Macro Functions - Editor Services               Chapter 13  Page 9
  3155.  
  3156.  
  3157.                                 ME USERS MANUAL
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.  
  3164.      When you press the <QUOTE> key, the prompt on  the  status  line  says
  3165.      "QUOTE".  The  character you press next will be inserted at the cursor
  3166.      position. You can use the ALT key  in  conjunction  with  the  numeric
  3167.      keypad to insert characters above 126. 
  3168.      
  3169.      <HELP>                                 <ALT> H
  3170.      
  3171.      This function calls the editor help routine.
  3172.      
  3173.      <OPTIONS>                              <ALT> O
  3174.      
  3175.      This  function  brings  up the options menu. The options menu contains
  3176.      the names of important editor variables and their values. To change  a
  3177.      value,  type  the  two-letter code for the parameter, a space, and the
  3178.      value. Typing <CTRL> D or <ESC> will return you to the editor. See the
  3179.      section on the editor variables for more information. 
  3180.      
  3181.      undo()                                 <ALT> U
  3182.      
  3183.      This function restores the last deleted line or block. Deleted lines and
  3184.      blocks are saved in a special system buffer. The undo() function inserts
  3185.      this buffer before the current line.
  3186.      
  3187.      <TEST KEYS>                            <ALT> <F10>
  3188.      
  3189.      This function prompts you for a keystroke,  and  prints  out  the  key
  3190.      value  for  that  keystroke.  The  key  value is the decimal value as-
  3191.      sociated with the keystroke. For values less than 127, it's the  ASCII
  3192.      code. For values above 127, it's (usually) the scan code plus 128. 
  3193.      
  3194.      This  can  be used with the assign_key() primitive or the <ASSIGN KEY>
  3195.      command to see what value a keystroke is associated with. 
  3196.      
  3197.      <ASSIGN KEY>                           <ALT> <F4>
  3198.      
  3199.      This function prompts you for a macro name  (which  has  already  been
  3200.      loaded), and asks you what keystroke it should be bound to. To use the
  3201.      <ASSIGN  KEY>  function  in  the  macro language, see the assign_key()
  3202.      primitive. 
  3203.      
  3204.      <TAB>                                  <TAB>
  3205.      
  3206.      This function inserts spaces until a tabstop is reached. The tab  fill
  3207.      character  is  initially a space (ASCII 32), but can be changed in the
  3208.      options menu. 
  3209.      
  3210.  
  3211.  
  3212.  
  3213.  
  3214.  
  3215.  
  3216.  
  3217.      Macro Functions - Editor Services               Chapter 13  Page 10
  3218.  
  3219.  
  3220.                                 ME USERS MANUAL
  3221.  
  3222.  
  3223.  
  3224.  
  3225.  
  3226.  
  3227.      os_command(cmd)                        <ALT> X
  3228.        string cmd;
  3229.      
  3230.      This function calls the DOS command interpreter to  perform  one  com-
  3231.      mand.  The  string 'cmd' contains the command to execute. 'Cmd' can be
  3232.      the string "command" if you want to enter the command interpreter  for
  3233.      an  extended  period  of time. To get back to the editor, type the DOS
  3234.      command "exit" at the DOS prompt. 
  3235.      This function returns the error code sent by the executed command.  An
  3236.      error code of 0 usually means successful completion.
  3237.      
  3238.      refresh()                              <ALT> R
  3239.      
  3240.      This  function redraws the screen. It's used if the screen happends to
  3241.      get messed up by "noise" over transmission lines, or if someone writes
  3242.      a message to your tty. 
  3243.      
  3244.      bookmark(ch)                           <ALT> B
  3245.        int ch;
  3246.        
  3247.      This function sets a "place marker" at the current  line  and  current
  3248.      column.  This  marker  is  named with letters 'a' through 'z'. You can
  3249.      have as many as 26 different place markers set at one time. 
  3250.      
  3251.  
  3252.  
  3253.  
  3254.  
  3255.  
  3256.  
  3257.  
  3258.  
  3259.  
  3260.  
  3261.  
  3262.  
  3263.  
  3264.  
  3265.  
  3266.  
  3267.  
  3268.  
  3269.  
  3270.  
  3271.  
  3272.  
  3273.  
  3274.  
  3275.  
  3276.  
  3277.  
  3278.  
  3279.  
  3280.      Macro Functions - Editor Services               Chapter 13  Page 11
  3281.  
  3282.  
  3283.                                 ME USERS MANUAL
  3284.  
  3285.  
  3286.  
  3287.  
  3288.  
  3289.  
  3290.                          BUFFERS AND THE MACRO LANGUAGE
  3291.      
  3292.      
  3293.          A "buffer" is an area which holds text. Each buffer has a name as-
  3294.      sociated with it, which is usually the name of the file where the text
  3295.      originated  from.  A buffer may be shown in a window on the screen, or
  3296.      may be invisible (ie the editor's "pick  buffers"  are  invisible).  A
  3297.      buffer may be shown in one window, or in multiple windows. 
  3298.      
  3299.         The editor keeps a list of  buffers  which  are  currently  in  ex-
  3300.      istence.  This  list can be envisioned as a circular list - the buffer
  3301.      that comes after the last buffer  is  the  first  buffer.  The  editor
  3302.      operations always deal with the currently active buffer. 
  3303.      
  3304.          Each buffer contains a unique identifier. The identifier is an in-
  3305.      teger  which  starts  at 1. Most of the buffer functions take an iden-
  3306.      tifier as an argument. You can always find out  the  identifier  of  a
  3307.      buffer by using the find_buffer() function. 
  3308.      
  3309.         The macro language contains functions which can manipulate buffers.
  3310.      These  functions DO NOT have any associated keystrokes - they are only
  3311.      available through macros. 
  3312.      
  3313.      
  3314.                                 BUFFER FUNCTIONS 
  3315.      
  3316.      create_buffer(filename)
  3317.        string filename; 
  3318.      
  3319.      DESCRIPTION 
  3320.      
  3321.          Create_buffer() will create a brand new buffer and  attach  it  to
  3322.      the  buffer list. The filename should be the name of the file that the
  3323.      buffer is associated with. The editor will search for a file with that
  3324.      name, and attempt to read the file into the new buffer. If there is no
  3325.      file by that name, then the buffer  will  initially  contain  a  blank
  3326.      line. 
  3327.      
  3328.          It  is  important  to note that the new buffer WILL NOT become the
  3329.      current buffer  unless  you  use  the  setcurrbuf()  function  or  the
  3330.      show_buffer() function. 
  3331.      
  3332.      ARGUMENTS 
  3333.      
  3334.          'Filename' is the name of the file that is associated with the new
  3335.      buffer. 
  3336.      
  3337.  
  3338.  
  3339.  
  3340.  
  3341.  
  3342.  
  3343.      Macro Functions - Buffer Services               Chapter 14  Page 1
  3344.  
  3345.  
  3346.                                 ME USERS MANUAL
  3347.  
  3348.  
  3349.  
  3350.  
  3351.  
  3352.  
  3353.      RETURNS 
  3354.      
  3355.          If  successful,  the ID of the new buffer will be returned. The ID
  3356.      is an integer greater than 0. If not successful, returns 0. 
  3357.      
  3358.      EXAMPLE 
  3359.      
  3360.        # The following code tells DOS to do a directory listing and  put
  3361.        # the output into a file called "foo". If this was successful, then
  3362.        # we will  create  a  new  buffer  and  read  "foo"  into it. If this was
  3363.        # successful, we will make the new buffer the current buffer, and
  3364.        # show it. 
  3365.      
  3366.        int id;
  3367.        if (os_command("dir > foo") && (id = create_buffer("foo")) > 0)
  3368.          show_buffer(id); 
  3369.      
  3370.      
  3371.      currbuf() 
  3372.      
  3373.      DESCRIPTION 
  3374.      
  3375.          Currbuf() returns the ID of the current buffer. 
  3376.      
  3377.      ARGUMENTS 
  3378.      
  3379.          None. 
  3380.      
  3381.      RETURNS 
  3382.      
  3383.          The ID of the current buffer, if one exists. The ID is an  integer
  3384.      greater than 0. If no buffer exists, then 0 is returned. 
  3385.      
  3386.      EXAMPLE 
  3387.      
  3388.        # See if we already have a buffer associated with the file foo.c. If
  3389.        # so, then set the current focus to that buffer. If invisible, the
  3390.        # buffer will remain invisible.
  3391.      
  3392.        int id; 
  3393.      
  3394.        id = find_buffer("foo.c");
  3395.        if (id > 0)
  3396.          setcurrbuf(id); 
  3397.      
  3398.      
  3399.  
  3400.  
  3401.  
  3402.  
  3403.  
  3404.  
  3405.  
  3406.      Macro Functions - Buffer Services               Chapter 14  Page 2
  3407.  
  3408.  
  3409.                                 ME USERS MANUAL
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415.  
  3416.      delete_buffer(id)
  3417.        int id; 
  3418.      
  3419.      DESCRIPTION 
  3420.      
  3421.          Delete_buffer()  removes  the  buffer  whose identifier is ID. The
  3422.      buffer is deleted from the buffer list,  and  any  windows  associated
  3423.      with  that  buffer will be deleted. This function does not set the new
  3424.      current buffer, nor the new current window.
  3425.      
  3426.          This function should be used with extreme caution. If  you  delete
  3427.      the current buffer, and then try to do editing operations without set-
  3428.      ting the new current buffer, chaos may result. 
  3429.      
  3430.      ARGUMENTS 
  3431.      
  3432.          The identifier of the buffer to delete. 
  3433.      
  3434.      RETURNS 
  3435.      
  3436.          Returns 1 if successful, 0 if not. 
  3437.      
  3438.      EXAMPLE 
  3439.      
  3440.        # This code deletes the buffer associated with file "foo.c". 
  3441.      
  3442.        int currid, id;
  3443.      
  3444.        currid = currbuf();
  3445.        id = find_buffer("foo.c");
  3446.        if (id > 0)
  3447.          delete_buffer(id);
  3448.        if (currid == id)   # watch out!!! We deleted the current buf
  3449.          show_buffer(next_buffer(id));   # set the new buffer
  3450.      
  3451.      
  3452.      
  3453.      find_buffer(name)
  3454.        string name; 
  3455.      
  3456.      DESCRIPTION 
  3457.      
  3458.          Find_buffer()  searches for a buffer named "name", and returns the
  3459.      identifier associated with that buffer. 
  3460.      
  3461.  
  3462.  
  3463.  
  3464.  
  3465.  
  3466.  
  3467.  
  3468.  
  3469.      Macro Functions - Buffer Services               Chapter 14  Page 3
  3470.  
  3471.  
  3472.                                 ME USERS MANUAL
  3473.  
  3474.  
  3475.  
  3476.  
  3477.  
  3478.  
  3479.      ARGUMENTS 
  3480.      
  3481.          The name of the buffer to be located. 
  3482.      
  3483.      RETURNS 
  3484.      
  3485.          The ID of the buffer is returned if the buffer was found. If  not,
  3486.      0 is returned. 
  3487.      
  3488.      EXAMPLE 
  3489.      
  3490.        int id; 
  3491.      
  3492.        if ((id = find_buffer("foo.c")) > 0) show_buffer(id); 
  3493.      
  3494.      
  3495.      next_buffer(id) 
  3496.        int id; 
  3497.      
  3498.      DESCRIPTION 
  3499.      
  3500.          Next_buffer()  returns  the  identifier  of the next buffer in the
  3501.      buffer list. The buffer list is circular, so the next buffer after the
  3502.      last buffer is the first buffer. 
  3503.      
  3504.      ARGUMENTS 
  3505.      
  3506.          'Id' is the identifier of the buffer to start at. 
  3507.      
  3508.      RETURNS 
  3509.      
  3510.          The identifier of the buffer  AFTER  the  buffer  with  identifier
  3511.      'id'. f there are no buffers associated with 'id', returns 0. 
  3512.      
  3513.      EXAMPLE 
  3514.      
  3515.        # This searches for the buffer whose identifier is 'id'.
  3516.      
  3517.        int desired_id;
  3518.        int id;
  3519.      
  3520.        id = currbuf();
  3521.        while (id != desired_id)
  3522.          id = next_buffer(id);
  3523.      
  3524.      
  3525.  
  3526.  
  3527.  
  3528.  
  3529.  
  3530.  
  3531.  
  3532.      Macro Functions - Buffer Services               Chapter 14  Page 4
  3533.  
  3534.  
  3535.                                 ME USERS MANUAL
  3536.  
  3537.  
  3538.  
  3539.  
  3540.  
  3541.  
  3542.      setcurrbuf(id)
  3543.        int id; 
  3544.      
  3545.      DESCRIPTION 
  3546.      
  3547.          Setcurrbuf()  makes  the buffer whose identifier is ID the current
  3548.      buffer. 
  3549.      
  3550.      ARGUMENTS 
  3551.      
  3552.          The identifier of the desired buffer. 
  3553.      
  3554.      RETURNS 
  3555.      
  3556.          The ID of the buffer is returned if successful. 0 is  returned  if
  3557.      the function failed. 
  3558.      
  3559.      EXAMPLE 
  3560.      
  3561.      
  3562.      show_buffer(id)
  3563.        int id; 
  3564.      
  3565.      DESCRIPTION 
  3566.      
  3567.          Show_buffer()  makes  the  buffer with identifier 'id' the current
  3568.      buffer. If there is no window  associated  with  the  buffer,  then  a
  3569.      window is created.
  3570.      
  3571.      ARGUMENTS 
  3572.      
  3573.          The integer identifier of the buffer to be shown.
  3574.      
  3575.      RETURNS 
  3576.      
  3577.          The identifier of the buffer if successful, 0 if not.
  3578.      
  3579.      EXAMPLE 
  3580.      
  3581.        int id;
  3582.      
  3583.        if ((id = find_buffer("foo.c")) > 0)
  3584.          show_buffer(id);
  3585.      
  3586.  
  3587.  
  3588.  
  3589.  
  3590.  
  3591.  
  3592.  
  3593.  
  3594.  
  3595.      Macro Functions - Buffer Services               Chapter 14  Page 5
  3596.  
  3597.  
  3598.                                ME USERS MANUAL
  3599.  
  3600.  
  3601.  
  3602.  
  3603.  
  3604.  
  3605.                              PRIMITIVE FUNCTIONS
  3606.     
  3607.         The  following  list  of  functions  can  be  used  in  the  macro
  3608.     programming  language  of  the editor. For each function, the name and
  3609.     optional aruments are given, along with a  brief  description  of  the
  3610.     function,  a  description  of  the  arguments and return value, and an
  3611.     example.
  3612.     
  3613.         We realize that you may need to have  a  primitive  which  doesn't
  3614.     exist.  If we were to include every primitive which every user wanted,
  3615.     then the number of primitives would become unwieldly.  Please  let  us
  3616.     know if you think that a certain primitive is absolutely imperative.
  3617.     
  3618.     
  3619.     assign_key(macroname, key)
  3620.       string macroname;
  3621.       int    key;
  3622.     
  3623.     DESCRIPTION
  3624.     
  3625.       Assigns the keystroke specified in "key" to the macro specified
  3626.       in "macroname". Whenever that keystroke is pressed, the named
  3627.       macro will be executed.
  3628.     
  3629.     ARGUMENTS
  3630.     
  3631.       "Macroname" is the name of the macro to be assigned, in quotes.
  3632.       "Key" is the value of the key. If you are not sure what the
  3633.       value of a key is, use the <TEST KEY> command (ALT F10) in the
  3634.       editor.
  3635.     
  3636.     RETURNS
  3637.     
  3638.       Returns the second argument if successful, 0 if not.
  3639.     
  3640.     EXAMPLE
  3641.     
  3642.       init()
  3643.       {
  3644.         .....
  3645.         assign_key("justify", 10);
  3646.         .....
  3647.       }
  3648.     
  3649.       justify()
  3650.       {
  3651.         .....
  3652.       }
  3653.  
  3654.  
  3655.  
  3656.  
  3657.  
  3658.  
  3659.     Macro Functions - Primitives                    Chapter 15  Page 1
  3660.  
  3661.  
  3662.                                ME USERS MANUAL
  3663.  
  3664.  
  3665.  
  3666.  
  3667.  
  3668.  
  3669.       The justify() macro is assigned to CTRL-J key (ASCII value 10).  
  3670.     The init() procedure is executed only once,  when the macro  file 
  3671.     is  initially loaded into the editor.  From now on,  any time you 
  3672.     press the CTRL_J key, the justify() macro will be done.  
  3673.     
  3674.     
  3675.      
  3676.      
  3677.     atoi(str)
  3678.       string str;
  3679.     
  3680.     DESCRIPTION
  3681.     
  3682.       Atoi() scans str for an integer and returns the value of the 
  3683.     integer. If the first character of the string is not a number (or 
  3684.     a valid numerical prefix, like '+' or '-'), then the ASCII value 
  3685.     of the first character is returned.
  3686.     
  3687.     ARGUMENTS
  3688.     
  3689.       Str is a string which should contain a numerical string 
  3690.     starting at the first character.
  3691.     
  3692.     RETURNS
  3693.     
  3694.       The integer value extracted from str.
  3695.     
  3696.     EXAMPLE
  3697.     
  3698.       string s;
  3699.       int    n;
  3700.     
  3701.       s = "123";
  3702.       n = atoi(s);    /* n is 123 */
  3703.       s = "ABC";
  3704.       n = atoi(s);    /* n is 65, the ASCII value of 'A' */
  3705.     
  3706.     
  3707.     
  3708.     
  3709.     bell()
  3710.     
  3711.     DESCRIPTION
  3712.     
  3713.         Bell()  sounds a tone on the PC. This is useful for alerting users
  3714.  
  3715.  
  3716.  
  3717.  
  3718.  
  3719.  
  3720.  
  3721.  
  3722.     Macro Functions - Primitives                    Chapter 15  Page 2
  3723.  
  3724.  
  3725.                                ME USERS MANUAL
  3726.  
  3727.  
  3728.  
  3729.  
  3730.  
  3731.  
  3732.     to a prompt, error condition, etc.
  3733.     
  3734.     ARGUMENTS
  3735.     
  3736.         None.
  3737.     
  3738.     RETURNS
  3739.     
  3740.         Nothing
  3741.     
  3742.     EXAMPLES
  3743.     
  3744.       if (x < 0)
  3745.       {
  3746.         bell();
  3747.         message("Number must be positive");
  3748.       }
  3749.     
  3750.     
  3751.     
  3752.     buffer_modified()
  3753.     
  3754.     DESCRIPTION
  3755.     
  3756.         Used to tell if the current buffer has been modified since it  was
  3757.     used this editing session.
  3758.     
  3759.     ARGUMENTS
  3760.     
  3761.         None.
  3762.     
  3763.     RETURNS
  3764.     
  3765.         Non-zero if the buffer has been modified, 0 if not.
  3766.     
  3767.     EXAMPLES
  3768.     
  3769.       if (buffer_modified())
  3770.       {
  3771.         bell();
  3772.         message("Buffer modified - quit anyway (y/n)");
  3773.         if ((c = get_tty_char()) == 'y' || c == 'Y')
  3774.           delete_buffer(currbuf());
  3775.       }
  3776.     
  3777.     
  3778.     
  3779.  
  3780.  
  3781.  
  3782.  
  3783.  
  3784.  
  3785.     Macro Functions - Primitives                    Chapter 15  Page 3
  3786.  
  3787.  
  3788.                                ME USERS MANUAL
  3789.  
  3790.  
  3791.  
  3792.  
  3793.  
  3794.  
  3795.     
  3796.     chr(c)
  3797.       int c;
  3798.     
  3799.     DESCRIPTION
  3800.     
  3801.         Chr()  takes  the  integer in c and returns a one-character string
  3802.     with c as the first character. C should be between  0  and  255.  This
  3803.     function  should  be  used  when  you   perform   certain   operations
  3804.     between strings, and one of the strings is an integer.
  3805.     
  3806.     ARGUMENTS
  3807.     
  3808.         'C' is an integer between 0 and 255.
  3809.     
  3810.     RETURNS
  3811.     
  3812.         The one-character string with the ASCII value of 'c' as the  first
  3813.     character.
  3814.     
  3815.     EXAMPLES
  3816.     
  3817.       int c;
  3818.     
  3819.       c = 's';
  3820.       str = "do";
  3821.       str = strcat(str, chr(c));      /* str will be "dos" */
  3822.     
  3823.       Note  that  if  chr() wasn't used, then str would have been "do115",
  3824.     since c is converted to a numeric string. The general rule is that  if
  3825.     a  function  expects  a  string  as  an  argument,  and you send it an
  3826.     integer, then the integer will be converted to a numeric string.
  3827.     
  3828.     
  3829.     
  3830.     
  3831.     clear_positions()
  3832.     
  3833.     DESCRIPTION
  3834.     
  3835.         Clear_positions() clears the stack of  saved  positions.  See  the
  3836.     save_position() and restore_position() functions.
  3837.     
  3838.     ARGUMENTS
  3839.     
  3840.         None.
  3841.     
  3842.  
  3843.  
  3844.  
  3845.  
  3846.  
  3847.  
  3848.     Macro Functions - Primitives                    Chapter 15  Page 4
  3849.  
  3850.  
  3851.                                ME USERS MANUAL
  3852.  
  3853.  
  3854.  
  3855.  
  3856.  
  3857.  
  3858.     RETURNS
  3859.     
  3860.         Nothing.
  3861.     
  3862.     EXAMPLES
  3863.     
  3864.         See the incremental search macro included with the editor.
  3865.     
  3866.     
  3867.     
  3868.     
  3869.     command(func)
  3870.       int func;
  3871.     
  3872.     DESCRIPTION
  3873.     
  3874.         Command()  takes a keystroke whose value is the integer 'func' and
  3875.     calls the editor's command  dispatcher  to  execute  the  command.  If
  3876.     you  have  a routine which dispatches on user keystrokes, and you need
  3877.     to invoke the default processing on the  keys  you  aren't  interested
  3878.     in,  this  function  can be used as a default command dispatcher. (See
  3879.     example below).
  3880.     
  3881.     ARGUMENTS
  3882.     
  3883.         'Func' is the integer keystroke between 0 and 255.
  3884.     
  3885.     RETURNS
  3886.     
  3887.         Nothing.
  3888.     
  3889.     EXAMPLES
  3890.     
  3891.       if ((c = get_tty_char()) == 145)
  3892.          ....
  3893.       else if (c == 203)
  3894.          ....
  3895.       else
  3896.         command(c);     /* call the editor to execute the keystroke */
  3897.     
  3898.     
  3899.     
  3900.     currchar()
  3901.     
  3902.     DESCRIPTION
  3903.     
  3904.       Returns the character under the cursor.
  3905.  
  3906.  
  3907.  
  3908.  
  3909.  
  3910.  
  3911.     Macro Functions - Primitives                    Chapter 15  Page 5
  3912.  
  3913.  
  3914.                                ME USERS MANUAL
  3915.  
  3916.  
  3917.  
  3918.  
  3919.  
  3920.  
  3921.     ARGUMENTS
  3922.     
  3923.       None.
  3924.     
  3925.     RETURNS
  3926.     
  3927.       An integer representing the ASCII value of the character.
  3928.     
  3929.     EXAMPLE
  3930.     
  3931.       /* advance cursor forward until a non-blank character is reached */
  3932.     
  3933.       while (!iseof() && currchar() == ' ')
  3934.         right();
  3935.     
  3936.     
  3937.     
  3938.     
  3939.     currcol()
  3940.     
  3941.     DESCRIPTION
  3942.     
  3943.       Returns the value of the column which the cursor is on.
  3944.     
  3945.     ARGUMENTS
  3946.     
  3947.       None.
  3948.     
  3949.     RETURNS
  3950.     
  3951.       An integer between 1 and 32767.
  3952.     
  3953.     EXAMPLE
  3954.     
  3955.       int col;
  3956.     
  3957.       col = currcol();
  3958.     
  3959.     
  3960.     
  3961.     currline()
  3962.     
  3963.     DESCRIPTION
  3964.     
  3965.       Returns the text of the current line (the line where the cursor 
  3966.     is).
  3967.  
  3968.  
  3969.  
  3970.  
  3971.  
  3972.  
  3973.  
  3974.     Macro Functions - Primitives                    Chapter 15  Page 6
  3975.  
  3976.  
  3977.                                ME USERS MANUAL
  3978.  
  3979.  
  3980.  
  3981.  
  3982.  
  3983.  
  3984.     
  3985.     ARGUMENTS
  3986.     
  3987.       None.
  3988.     
  3989.     
  3990.     
  3991.     
  3992.     currlinenum()
  3993.     
  3994.     DESCRIPTION
  3995.     
  3996.       Returns the line number of the current line.
  3997.     
  3998.     ARGUMENTS
  3999.     
  4000.       None.
  4001.     
  4002.     RETURNS
  4003.     
  4004.       A number between 1 and the last line of the file.
  4005.     
  4006.     EXAMPLE
  4007.     
  4008.     /* THIS CODE DELETES ALL LINES FROM THE BEGINNING OF THE FILE  */
  4009.     /* UNTIL (BUT NOT INCLUDING) THE CURRENT LINE */
  4010.     
  4011.     del_from_bof()
  4012.     {
  4013.       int i, endline;
  4014.     
  4015.       endline = currlinenum();
  4016.       goline(1);
  4017.     
  4018.       for (i = 1;  i < endline;  i = i + 1)
  4019.         delline();      
  4020.     }
  4021.     
  4022.     
  4023.     
  4024.     
  4025.     filename()
  4026.     
  4027.  
  4028.  
  4029.  
  4030.  
  4031.  
  4032.  
  4033.  
  4034.  
  4035.  
  4036.  
  4037.     Macro Functions - Primitives                    Chapter 15  Page 7
  4038.  
  4039.  
  4040.                                ME USERS MANUAL
  4041.  
  4042.  
  4043.  
  4044.  
  4045.  
  4046.  
  4047.     DESCRPTION
  4048.     
  4049.       Returns the filename of the file currently being edited.
  4050.     
  4051.     ARGUMENTS
  4052.     
  4053.       None.
  4054.     
  4055.     RETURNS
  4056.     
  4057.       A string result.
  4058.     
  4059.       
  4060.     
  4061.     
  4062.     get_tty_char()
  4063.     
  4064.     DESCRIPTION
  4065.     
  4066.       Waits for the user to press a key, and returns the value of 
  4067.     that keystroke.
  4068.     
  4069.     ARGUMENTS
  4070.     
  4071.       None.
  4072.     
  4073.     RETURNS
  4074.     
  4075.       The integer value of the keystroke.
  4076.     
  4077.     EXAMPLE
  4078.     
  4079.       message("Do you really want to do this?");
  4080.       if ((c = get_tty_char()) == 'Y' || c == 'y')
  4081.         doit();
  4082.     
  4083.     
  4084.     
  4085.     get_tty_str(prompt)
  4086.       string prompt;
  4087.     
  4088.     DESCRIPTION
  4089.     
  4090.       Displays the prompt on the status line, then waits for the user 
  4091.     to enter a string (ended by hitting RETURN). In addition to this
  4092.     function being useful for getting information from the user, it is
  4093.     also useful for debugging your macros (see below).
  4094.     
  4095.  
  4096.  
  4097.  
  4098.  
  4099.  
  4100.  
  4101.     Macro Functions - Primitives                    Chapter 15  Page 8
  4102.  
  4103.  
  4104.                                ME USERS MANUAL
  4105.  
  4106.  
  4107.  
  4108.  
  4109.  
  4110.  
  4111.     ARGUMENTS
  4112.     
  4113.       The text of the prompt.
  4114.     
  4115.     RETURNS
  4116.     
  4117.       The string that the user typed in.
  4118.     
  4119.     EXAMPLE
  4120.     
  4121.       int n;
  4122.       string foo;
  4123.       
  4124.       .......
  4125.       /* display info, and wait for user to acknowledge  */
  4126.       foo = get_tty_str(sprintf("The value of n is %d", n)); 
  4127.     
  4128.     
  4129.     
  4130.     
  4131.     index(str, pat)
  4132.       string str;
  4133.       string pat;
  4134.     
  4135.     DESCRIPTION
  4136.     
  4137.       Locates the first occurence of the string 'pat' within the string 'str'.
  4138.     
  4139.     ARGUMENTS
  4140.     
  4141.       'Str' is the string to search through.
  4142.       'Pat' is the string to search for. The length of this string should be
  4143.     less than or equal to the length of 'str'.
  4144.     
  4145.     RETURNS
  4146.     
  4147.       The position in 'str' where the first occurence of 'pat' is found. This
  4148.     position is between 1 and the length of 'str'. If 'pat' is not found, 0 is
  4149.     returned.
  4150.     
  4151.     EXAMPLE
  4152.     
  4153.       /* The following piece of code changes all occurences of "Mrs." to
  4154.          "Miss" on the current line. */
  4155.     
  4156.       int savecol, i, j;
  4157.     
  4158.  
  4159.  
  4160.  
  4161.  
  4162.  
  4163.  
  4164.     Macro Functions - Primitives                    Chapter 15  Page 9
  4165.  
  4166.  
  4167.                                ME USERS MANUAL
  4168.  
  4169.  
  4170.  
  4171.  
  4172.  
  4173.  
  4174.       savecol = currcol();     /* save the current cursor position */
  4175.     
  4176.       while ((i = index(currline(), "Mrs.")) > 0)
  4177.       {
  4178.         setcol(i+1);                       /* move to the "r" in "Mrs." */
  4179.         insert("iss");                     /* add "iss" to the line */
  4180.         for (j = 1;  j <= 3;  j = j + 1)   /* get rid of the "rs." */
  4181.           delchar();
  4182.       }
  4183.     
  4184.       setcol(savecol);         /* return to the old cursor position */
  4185.     
  4186.     
  4187.      
  4188.     insert(str)
  4189.       string str;
  4190.     
  4191.     DESCRIPTION
  4192.     
  4193.         Insert()  takes  the  string  'str'  and inserts it at the current
  4194.     cursor position. This has the same effect as  if  you  had  typed  the
  4195.     characters  in  the string on the keyboard. Characters to the right of
  4196.     the inserted string will be pushed over.
  4197.     
  4198.     ARGUMENTS
  4199.     
  4200.         Str  is  the string which will be inserted. If you have an integer
  4201.     variable between 0 and 255, and you would like to insert it, then  you
  4202.     must use the chr() function.
  4203.     
  4204.     RETURNS
  4205.     
  4206.         Nothing.
  4207.     
  4208.     
  4209.     
  4210.     
  4211.     is_bof()
  4212.     
  4213.     DESCRIPTION
  4214.     
  4215.       Returns 1 if the cursor is at the first character of the file, 0 if
  4216.     not.
  4217.     
  4218.     ARGUMENTS
  4219.     
  4220.       None.
  4221.  
  4222.  
  4223.  
  4224.  
  4225.  
  4226.  
  4227.     Macro Functions - Primitives                    Chapter 15  Page 10
  4228.  
  4229.  
  4230.                                ME USERS MANUAL
  4231.  
  4232.  
  4233.  
  4234.  
  4235.  
  4236.  
  4237.     
  4238.     RETURNS
  4239.     
  4240.       See above.
  4241.     
  4242.     
  4243.     
  4244.     
  4245.     is_bol()
  4246.     
  4247.     DESCRIPTION
  4248.     
  4249.       Returns 1 if the cursor is at the beginning of the current line, 0 if not.
  4250.     
  4251.     ARGUMENTS
  4252.     
  4253.       None.
  4254.     
  4255.     RETURNS
  4256.     
  4257.       See above.
  4258.     
  4259.     
  4260.     
  4261.     
  4262.     is_eof()
  4263.     
  4264.     DESCRIPTION
  4265.     
  4266.       Returns 1 if the cursor is just past the last character of the file, 0 if 
  4267.     not.
  4268.     
  4269.     ARGUMENTS
  4270.     
  4271.       None.
  4272.     
  4273.     RETURNS
  4274.       See above.
  4275.     
  4276.     
  4277.     
  4278.     
  4279.     is_eol()
  4280.     
  4281.     DESCRIPTION
  4282.     
  4283.       Returns 1 if the cursor is past the last character of the current line, 0 if 
  4284.  
  4285.  
  4286.  
  4287.  
  4288.  
  4289.  
  4290.     Macro Functions - Primitives                    Chapter 15  Page 11
  4291.  
  4292.  
  4293.                                ME USERS MANUAL
  4294.  
  4295.  
  4296.  
  4297.  
  4298.  
  4299.  
  4300.     not.
  4301.     
  4302.     ARGUMENTS
  4303.     
  4304.       None.
  4305.     
  4306.     RETURNS
  4307.     
  4308.       See above.
  4309.     
  4310.     
  4311.     
  4312.      
  4313.     is_linemarked()
  4314.     
  4315.     DESCRIPTION
  4316.     
  4317.         Is_linemarked()  is  used to tell if the current line is marked. A
  4318.     line can be marked with the <MARK LINE> command (ALT F7), or the <MARK
  4319.     GROUP> command (ALT F8).
  4320.     
  4321.     ARGUMENTS
  4322.     
  4323.         None.
  4324.     
  4325.     RETURNS
  4326.     
  4327.         Returns 1 if the current line is marked, 0 if not.
  4328.     
  4329.     EXAMPLE
  4330.     
  4331.       /* This loop changes all marked lines to uppercase characters. Assume
  4332.          that the user wrote a routine called uppercase() which changes the
  4333.          current line to all uppercase. */
  4334.     
  4335.       gobof();              /* move to the first line */
  4336.       while (currlinenum() <= lastlinenum())
  4337.       {
  4338.         if (is_linemarked())
  4339.           uppercase();      /*  assume this is a user written routine */
  4340.         down();
  4341.       }
  4342.     
  4343.     
  4344.         As an aside, the above loop would run faster if we kept a variable
  4345.     as the line counter, like :
  4346.     
  4347.  
  4348.  
  4349.  
  4350.  
  4351.  
  4352.  
  4353.     Macro Functions - Primitives                    Chapter 15  Page 12
  4354.  
  4355.  
  4356.                                ME USERS MANUAL
  4357.  
  4358.  
  4359.  
  4360.  
  4361.  
  4362.  
  4363.       i = 1;
  4364.       last = lastlinenum();
  4365.       while (i <= last)
  4366.         .....
  4367.         i = i + 1;
  4368.     
  4369.     
  4370.     
  4371.     itoa(n)
  4372.       int n;
  4373.     
  4374.     DESCRIPTION
  4375.     
  4376.       Converts the integer 'n' to a string.
  4377.     
  4378.     ARGUMENTS
  4379.     
  4380.       'N' is the number to convert. The value of 'n' is not changed.
  4381.     
  4382.     RETURNS
  4383.     
  4384.       The string which represents the number. This string is dynamically 
  4385.     allocated.
  4386.     
  4387.     EXAMPLE
  4388.     
  4389.       string linenum;
  4390.     
  4391.       linenum = itoa(currlinenum());
  4392.       message(strcat("We are on line ", linenum));
  4393.       
  4394.     
  4395.     
  4396.     
  4397.     
  4398.     lastlinenum()
  4399.     
  4400.     DESCRIPTION
  4401.     
  4402.       Returns the line number of the last line in the current buffer.
  4403.     
  4404.     ARGUMENTS
  4405.     
  4406.       None.
  4407.     
  4408.     RETURNS
  4409.     
  4410.  
  4411.  
  4412.  
  4413.  
  4414.  
  4415.  
  4416.     Macro Functions - Primitives                    Chapter 15  Page 13
  4417.  
  4418.  
  4419.                                ME USERS MANUAL
  4420.  
  4421.  
  4422.  
  4423.  
  4424.  
  4425.  
  4426.       An integer.
  4427.     
  4428.     EXAMPLE
  4429.     
  4430.       /* The following statement moves the currentline to  the  last  line
  4431.       */
  4432.     
  4433.       goline(lastlinenum());
  4434.     
  4435.     
  4436.     
  4437.     
  4438.     ltrim(str)
  4439.       string str;
  4440.     
  4441.     DESCRIPTION
  4442.     
  4443.       Ltrim() trims all leading blanks from the string 'str'.
  4444.     
  4445.     ARGUMENTS
  4446.     
  4447.       'Str' is the string to trim.
  4448.     
  4449.     RETURNS
  4450.     
  4451.       Nothing.
  4452.     
  4453.     
  4454.     
  4455.     
  4456.     
  4457.     marked_col()
  4458.     
  4459.     DESCRIPTION
  4460.     
  4461.       If the mark is set, returns the column which the marker is on. Otherwise,
  4462.       returns 0.
  4463.       
  4464.     ARGUMENTS
  4465.     
  4466.       None.
  4467.       
  4468.     RETURNS
  4469.      
  4470.       See above.
  4471.     
  4472.     
  4473.  
  4474.  
  4475.  
  4476.  
  4477.  
  4478.  
  4479.     Macro Functions - Primitives                    Chapter 15  Page 14
  4480.  
  4481.  
  4482.                                ME USERS MANUAL
  4483.  
  4484.  
  4485.  
  4486.  
  4487.  
  4488.  
  4489.     
  4490.     
  4491.     marked_line()
  4492.     
  4493.     DESCRIPTION
  4494.     
  4495.       If the mark is set, returns the line number of the line which the marker
  4496.       is on. Otherwise, returns 0.
  4497.       
  4498.     ARGUMENTS
  4499.     
  4500.       None.
  4501.       
  4502.     RETURNS
  4503.      
  4504.       See above.
  4505.     
  4506.     
  4507.     
  4508.     
  4509.     message(str)
  4510.       string str;
  4511.       
  4512.     DESCRIPTION
  4513.     
  4514.       Displays the string 'str' on the status line. 
  4515.       
  4516.     ARGUMENTS
  4517.     
  4518.       The message to print.
  4519.       
  4520.     RETURNS
  4521.      
  4522.       Nothing.
  4523.     
  4524.     
  4525.     
  4526.     
  4527.     repstr(str, n)
  4528.       string str;
  4529.       int    n;
  4530.       
  4531.     DESCRIPTION
  4532.     
  4533.       Replicates string 'str' 'n' times. String 'str' is NOT altered.
  4534.     
  4535.     ARGUMENTS
  4536.  
  4537.  
  4538.  
  4539.  
  4540.  
  4541.  
  4542.     Macro Functions - Primitives                    Chapter 15  Page 15
  4543.  
  4544.  
  4545.                                ME USERS MANUAL
  4546.  
  4547.  
  4548.  
  4549.  
  4550.  
  4551.  
  4552.     
  4553.       String 'str' contains the string to replicate. 'N' is an integer which is
  4554.       the number of times to replicate the string.
  4555.     
  4556.     RETURNS
  4557.     
  4558.       Returns the new string.
  4559.     
  4560.     EXAMPLE
  4561.     
  4562.       /* This statement inserts a slash, followed by 30 asterisks, */
  4563.       /* followed by a slash, into the file. */
  4564.       insert(strcat( "/", strcat(repstr("*", 30), "/") ));
  4565.     
  4566.     
  4567.     
  4568.     
  4569.     restore_position()
  4570.     
  4571.     DESCRIPTION
  4572.     
  4573.         Restore_position()  sets  the cursor to the last position that was
  4574.     saved on the position stack. This position will be  removed  from  the
  4575.     stack. See the save_position() function for more information.
  4576.     
  4577.     ARGUMENTS
  4578.     
  4579.         None.
  4580.     
  4581.     RETURNS
  4582.     
  4583.         Nothing.
  4584.     
  4585.     EXAMPLES
  4586.     
  4587.       save_position();
  4588.     
  4589.       goline(200);
  4590.       insert("foo");
  4591.     
  4592.       restore_position();
  4593.     
  4594.         See also the incremental search macro included with the editor.
  4595.     
  4596.     
  4597.     
  4598.  
  4599.  
  4600.  
  4601.  
  4602.  
  4603.  
  4604.  
  4605.     Macro Functions - Primitives                    Chapter 15  Page 16
  4606.  
  4607.  
  4608.                                ME USERS MANUAL
  4609.  
  4610.  
  4611.  
  4612.  
  4613.  
  4614.  
  4615.     rtrim(str)
  4616.       string str;
  4617.     
  4618.     DESCRIPTION
  4619.     
  4620.       Rtrim() trims all trailing blanks from the string 'str'.
  4621.     
  4622.     ARGUMENTS
  4623.     
  4624.       'Str' is the string to trim.
  4625.     
  4626.     RETURNS
  4627.     
  4628.       Nothing.
  4629.     
  4630.     
  4631.     
  4632.     
  4633.     save_position()
  4634.     
  4635.     DESCRIPTION
  4636.     
  4637.         Save_position() places the current cursor position on the position
  4638.     stack.  The  position  stack  records the current line and the current
  4639.     column where the cursor is. To return to a previous position, use  the
  4640.     restore_position function.
  4641.     
  4642.     ARGUMENTS
  4643.     
  4644.         None.
  4645.     
  4646.     RETURNS
  4647.     
  4648.         Nothing.
  4649.     
  4650.     EXAMPLES
  4651.     
  4652.       save_position();
  4653.     
  4654.       goline(200);
  4655.       insert("foo");
  4656.     
  4657.       restore_position();
  4658.     
  4659.         See also the incremental search macro included with the editor.
  4660.     
  4661.     
  4662.     
  4663.  
  4664.  
  4665.  
  4666.  
  4667.  
  4668.  
  4669.     Macro Functions - Primitives                    Chapter 15  Page 17
  4670.  
  4671.  
  4672.                                ME USERS MANUAL
  4673.  
  4674.  
  4675.  
  4676.  
  4677.  
  4678.  
  4679.     
  4680.     setbufnum(n)
  4681.       int n;
  4682.       
  4683.     DESCRIPTION
  4684.     
  4685.       Changes the current pick buffer number to number 'n'.
  4686.     
  4687.     ARGUMENTS
  4688.     
  4689.       The integer 'n' must be between 0 and 9. 0 is the default buffer that
  4690.       the editor initially uses for all cut and paste operations.
  4691.     
  4692.     RETURNS
  4693.     
  4694.       1 if successful, 0 if not.
  4695.     
  4696.     
  4697.     
  4698.     
  4699.     setcol(col)
  4700.       int col;
  4701.       
  4702.     DESCRIPTION
  4703.     
  4704.       Move the cursor to column 'col' on the current line.
  4705.     
  4706.     ARGUMENTS
  4707.     
  4708.       'Col' is the integer column to move to.
  4709.     
  4710.     RETURNS
  4711.     
  4712.       The column number if successful, 0 if not.
  4713.     
  4714.     EXAMPLE
  4715.     
  4716.     /* This function simulates the <GOTO END OF LINE> key. */
  4717.     
  4718.     go_eol()
  4719.     {
  4720.       setcol( strlen(currline()) + 1 );
  4721.     }
  4722.     
  4723.     
  4724.      
  4725.      
  4726.  
  4727.  
  4728.  
  4729.  
  4730.  
  4731.  
  4732.     Macro Functions - Primitives                    Chapter 15  Page 18
  4733.  
  4734.  
  4735.                                ME USERS MANUAL
  4736.  
  4737.  
  4738.  
  4739.  
  4740.  
  4741.  
  4742.     setprompt(n)
  4743.       int n;
  4744.       
  4745.     DESCRIPTION
  4746.     
  4747.       Enables or disables the prompting that the editor uses for certain commands.
  4748.     
  4749.     ARGUMENTS
  4750.     
  4751.       0 if prompts should be turned off, a non-zero if they should be turned on.
  4752.     
  4753.     RETURNS
  4754.     
  4755.       Nothing.
  4756.     
  4757.     EXAMPLE
  4758.     
  4759.       setprompt(0);
  4760.     
  4761.     
  4762.     
  4763.     
  4764.     sprintf(format[, args])
  4765.       string format;
  4766.     
  4767.     DESCRIPTION
  4768.     
  4769.       Formats  a string according to the format string parameter. The for-
  4770.     mat string 'format' consists of a combination of characters  to  print
  4771.     and  format specifiers. Each format specifier describes a way to print
  4772.     out a certain argument. 
  4773.     
  4774.         The format specifiers currently accepted are
  4775.     
  4776.       %d  decimal integer
  4777.       %s  string
  4778.     
  4779.     ARGUMENTS
  4780.       
  4781.       'Format' is the format string. The format string consists of a combination
  4782.     of literal characters and format specifiers.
  4783.       'Args' is a list of 0 or more arguments. Argument i corresponds to format 
  4784.     specifier i in the format string.
  4785.     
  4786.     RETURNS
  4787.     
  4788.       The formatted string.
  4789.  
  4790.  
  4791.  
  4792.  
  4793.  
  4794.  
  4795.     Macro Functions - Primitives                    Chapter 15  Page 19
  4796.  
  4797.  
  4798.                                ME USERS MANUAL
  4799.  
  4800.  
  4801.  
  4802.  
  4803.  
  4804.  
  4805.     
  4806.     EXAMPLE
  4807.     
  4808.       string foo;
  4809.     
  4810.       foo = get_tty_str(sprintf("Col %d  Line %d of %d",
  4811.                                            currcol(), currline(), lastline()));
  4812.     
  4813.     
  4814.     
  4815.     
  4816.     strcat(s1, s2)
  4817.       string s1, s2;
  4818.       
  4819.     DESCRIPTION
  4820.     
  4821.       Appends string 's2' to the end of string 's1'.
  4822.       
  4823.     ARGUMENTS
  4824.     
  4825.       'S1' and 's2' must both be strings. If either are integers, then they
  4826.     are converted to strings before the append takes place.
  4827.     
  4828.     RETURNS
  4829.     
  4830.       Returns 's1', which contains the appended result.
  4831.       
  4832.     EXAMPLE
  4833.     
  4834.       insert(strcat("The current buffer name is ", filename()));
  4835.     
  4836.     
  4837.     
  4838.     
  4839.     strlen(str)
  4840.       string str;
  4841.     
  4842.     DESCRIPTION
  4843.     
  4844.       Returns the length of the string in 'str'.
  4845.     
  4846.     ARGUMENTS
  4847.     
  4848.       'Str' is the string to examine.
  4849.     
  4850.     RETURNS
  4851.     
  4852.  
  4853.  
  4854.  
  4855.  
  4856.  
  4857.  
  4858.     Macro Functions - Primitives                    Chapter 15  Page 20
  4859.  
  4860.  
  4861.                                ME USERS MANUAL
  4862.  
  4863.  
  4864.  
  4865.  
  4866.  
  4867.  
  4868.       An integer length >= 0.
  4869.     
  4870.     
  4871.     
  4872.     
  4873.     substr(str, pos, len)
  4874.       string str;
  4875.       int    pos;
  4876.       int    len;
  4877.     
  4878.     DESCRIPTION
  4879.     
  4880.       Extracts 'len' characters from the string in 'str' starting at position
  4881.     'pos'.
  4882.     
  4883.     ARGUMENTS
  4884.     
  4885.       'Str' is the string to examine.
  4886.       'Pos' is the position in 'str' to start at. Pos should be a number between 1 
  4887.       and the length of the string.
  4888.       'Len' is the number of characters to extract.
  4889.     
  4890.     RETURNS
  4891.     
  4892.       The string extracted.
  4893.      
  4894.     EXAMPLE
  4895.     
  4896.       dotpos = index(filename(), ".");
  4897.       if (dotpos > 0)
  4898.         root = substr(filename(), 1, dotpos - 1);
  4899.       else
  4900.         root = filename();
  4901.     
  4902.     
  4903.     
  4904.     tabs(str)
  4905.       string str;
  4906.     
  4907.     DESCRIPTION
  4908.     
  4909.         Tabs() is used to set the tab stops.
  4910.     
  4911.     ARGUMENTS
  4912.     
  4913.         Str  is  a  string  which contains a list of tab stops. The string
  4914.     consists a numbers separated by one  or  more  blanks.
  4915.  
  4916.  
  4917.  
  4918.  
  4919.  
  4920.  
  4921.     Macro Functions - Primitives                    Chapter 15  Page 21
  4922.  
  4923.  
  4924.                                ME USERS MANUAL
  4925.  
  4926.  
  4927.  
  4928.  
  4929.  
  4930.  
  4931.     
  4932.     RETURNS
  4933.     
  4934.         Nothing.
  4935.     
  4936.     EXAMPLE
  4937.     
  4938.       tabs("10 16 25 36");
  4939.     
  4940.     
  4941.     
  4942.     ungetc(c)
  4943.       int c;
  4944.     
  4945.     DESCRIPTION
  4946.     
  4947.         Ungetc()  pushes the character 'c' back onto the input stream. The
  4948.     next time that the editor goes to read a character, 'c' will be  read.
  4949.     There is no limit as to the number of characters you can push back.
  4950.     
  4951.     ARGUMENTS
  4952.     
  4953.         'C'  is the character to push back. It can be the values 0 through
  4954.     255.
  4955.     
  4956.     RETURNS
  4957.     
  4958.         Nothing.
  4959.     
  4960.  
  4961.  
  4962.  
  4963.  
  4964.  
  4965.  
  4966.  
  4967.  
  4968.  
  4969.  
  4970.  
  4971.  
  4972.  
  4973.  
  4974.  
  4975.  
  4976.  
  4977.  
  4978.  
  4979.  
  4980.  
  4981.  
  4982.  
  4983.  
  4984.     Macro Functions - Primitives                    Chapter 15  Page 22
  4985.  
  4986.  
  4987.                                 ME USERS MANUAL
  4988.  
  4989.  
  4990.  
  4991.  
  4992.  
  4993.  
  4994.                              REMAPPING THE KEYBOARD
  4995.      
  4996.          A  character  that  you  type at the keyboard can take on 256 dif-
  4997.      ferent values, from 0 to 255. On the IBM PC, the ASCII characters  are
  4998.      numbered  from  0 to 127, and the IBM extended characters are numbered
  4999.      from 128 to 255. All of the  function  key  combinations  and  numeric
  5000.      keypad combinations fall into the extended character set. 
  5001.      
  5002.          The  editor  has  an internal table which is used to translate one
  5003.      value into another. This internal table is 256 bytes long, with byte 0
  5004.      holding the translation value for keystroke value 0,  byte  1  holding
  5005.      the  value for keystroke 1, etc. The default values for this table in-
  5006.      dicate no translations (ie keystroke number n is translated into value
  5007.      n.) 
  5008.      
  5009.      
  5010.                             AN EXAMPLE OF REMAPPING
  5011.      
  5012.          As an example where translation may be desirable, let's consider a
  5013.      very simple remapping of the keyboard. The command that is  associated
  5014.      with  the  F1  function key is <DELETE LINE>. Let's say that you would
  5015.      like the <HELP> function to be assigned to the F1 key, and the <DELETE
  5016.      LINE> function assigned to the <ALT>  D  key.  Currently,  the  <HELP>
  5017.      function is assigned to the <ALT> H key. 
  5018.      
  5019.          To  find  out  what  keystroke  values the F1, <ALT> D and <ALT> H
  5020.      keys   produce,   use   the  <TEST  KEYS>  command  from  the  editor.
  5021.      This command is done by pressing the ALT F10 key. The <TEST KEYS> com-
  5022.      mand prompts you for a keystroke, and then prints the value  that  the
  5023.      keystroke produced. 
  5024.      
  5025.          After invoking the <TEST KEYS> command, we find that the following
  5026.      values are produced :
  5027.      
  5028.        F1     187
  5029.        ALT D   60
  5030.        ALT H  163
  5031.      
  5032.          What we would like to do is have the F1 key "generate" the <ALT> H
  5033.      keystroke,  and have the <ALT> D key "generate" the F1 value. In other
  5034.      words, we would like to fool the editor into thinking that when the F1
  5035.      key is pressed, the <ALT> H key was really pressed.
  5036.      
  5037.          To effect these changes, we would like to put the value  163  into
  5038.      byte  187  of the table, and put value 187 into byte 160 of the table.
  5039.      How can we do this without  going  altering  the  editor's  executable
  5040.      file?
  5041.  
  5042.  
  5043.  
  5044.  
  5045.  
  5046.  
  5047.      Remapping the Keyboard                          Appendix A  Page 1
  5048.  
  5049.  
  5050.                                 ME USERS MANUAL
  5051.  
  5052.  
  5053.  
  5054.  
  5055.  
  5056.  
  5057.      
  5058.      
  5059.                                THE KEYTABLE FILE
  5060.      
  5061.          The file which holds the keystroke translation  values  is  called
  5062.      "KEYTABLE.ME".  When  the editor starts up, it will first look in your
  5063.      current subdirectory for the KEYTABLE.ME file. If the  editor  doesn't
  5064.      find  it  there, then the editor will search the directories listed in
  5065.      your DOS search path. If this file still isn't  found,  then  the  in-
  5066.      ternal  table  is  filled  sequentially with the values 0 through 255.
  5067.      This means that no remapping will be performed. 
  5068.      
  5069.          The KEYTABLE.ME file contains one or more  tables  which  are  256
  5070.      bytes long, with byte i corresponding to keystroke i. The editor comes
  5071.      with  a default KEYTABLE.ME file. It also comes with several utilities
  5072.      to create and alter the KEYTABLE.ME file. 
  5073.      
  5074.          The  first  utility we will talk about is called KEYCOMP.EXE. This
  5075.      program  reads  a  keystroke  configuration  file  and   generates   a
  5076.      KEYTABLE.ME  file  from  it. A keystroke configuration file contains a
  5077.      list of keystrokes and their corresponding values. 
  5078.      
  5079.          Each line of the keystroke configuration file has the form :
  5080.      
  5081.        key=func
  5082.      
  5083.          The  "key"  can  be  a  decimal number, a single character between
  5084.      single quotes, ^char (a control character between 0 and 31), F#  where
  5085.      '#'  is a number between 1 and 10 (this is a normal function key), AF#
  5086.      (ALT function key), SF# (SHIFT function key), CF# (CTRL function key),
  5087.      or @char (ALT character key).
  5088.      
  5089.          "Func" is a number representing the value that the key produces.
  5090.      
  5091.          Here are some examples :
  5092.      
  5093.        120=122   (the key with the value 120 produces 122)
  5094.        '#'=289   (a pound sign produces 289)
  5095.        ^C=14     (CTRL C produces 14)
  5096.        F1=160    (F1 produces 160)
  5097.        @A=198    (ALT A produces 198)
  5098.        SF9=130   (SHIFT f9 produces 130)
  5099.      
  5100.          Any keystrokes which aren't mentioned in  the  configuration  file
  5101.      will just be translated into themselves.
  5102.      
  5103.          To run the keystroke compiler, type the command
  5104.  
  5105.  
  5106.  
  5107.  
  5108.  
  5109.  
  5110.      Remapping the Keyboard                          Appendix A  Page 2
  5111.  
  5112.  
  5113.                                 ME USERS MANUAL
  5114.  
  5115.  
  5116.  
  5117.  
  5118.  
  5119.  
  5120.      
  5121.          KEYCOMP filename
  5122.      
  5123.      where  filename  is  the  name of the keystroke configuration file. If
  5124.      everything goes well, the KEYTABLE.ME file will be  created.  You  can
  5125.      not  TYPE  out  the  KEYTABLE.ME  file  since it contains binary data.
  5126.      However, you can examine it with various disk utilities (such  as  the
  5127.      NORTON Utilities). 
  5128.      
  5129.          The second utility is called KEYCONF.EXE. This program generates a
  5130.      default keystroke configuration file.  There  are  256  lines  in  the
  5131.      generated file. The file looks like this : 
  5132.      
  5133.      0=0
  5134.      1=1
  5135.      255=255
  5136.      
  5137.          The  output  from  this  program is written to the screen. You can
  5138.      redirect the output to a file be giving the command :
  5139.          
  5140.          KEYCONF > keyfile (or any other name)
  5141.      
  5142.          Once  this  sample  keystroke configuration file is generated, you
  5143.      can alter  it  with  any  text  editor,  and  then  compile  it  using
  5144.      KEYCOMP.EXE. 
  5145.      
  5146.          The third utility is called KEYTEST.EXE. This  program  waits  for
  5147.      you  to  type  a  keystroke,  and  then  prints  out the value of that
  5148.      keystroke. Hitting the <ESC> key will stop the program.  This  program
  5149.      is also simulated by the <TEST KEYS> command of the editor. 
  5150.      
  5151.      
  5152.                                     PREFIXES
  5153.      
  5154.          Some  people  would like to have the editor emulate their favorite
  5155.      word processor, and hence, will make key maps which map  the  function
  5156.      keys  of  the  editor  into  the  keystrokes that their word processor
  5157.      requires.  Some  word  processors  use  a  two-keystroke  sequence  to
  5158.      generate  a  command.  One  of the most well-known examples of this is
  5159.      WordStar (WordStar is a trademark of MicroPro Inc.). For instance, the
  5160.      keystroke sequence CTRL K D is used to exit WordStar.
  5161.      
  5162.          You can specify prefixes in the keystroke redefinition file  which
  5163.      is compiled by the KEYCOMP.EXE program. A prefix line is of the form :
  5164.      
  5165.        PREFIX <keystroke>
  5166.      
  5167.  
  5168.  
  5169.  
  5170.  
  5171.  
  5172.  
  5173.      Remapping the Keyboard                          Appendix A  Page 3
  5174.  
  5175.  
  5176.                                 ME USERS MANUAL
  5177.  
  5178.  
  5179.  
  5180.  
  5181.  
  5182.  
  5183.          The  PREFIX  statement creates a 256 byte table which contains the
  5184.      commands generated by the second key of the sequence. As  an  example,
  5185.      you  press  CTRL  D  right  now to exit the editor. CTRL D generates a
  5186.      keystroke value of 4. If you would like to use the CTRL K D  keystroke
  5187.      combination  to  exit  the  editor  instead,  then your keystroke file
  5188.      should contain a line like this :
  5189.      
  5190.        PREFIX ^K
  5191.        .....        list of CTRL K commands
  5192.        D=4
  5193.        ......
  5194.      
  5195.      
  5196.          A prefix command table ends when the compiler  encounters  another
  5197.      PREFIX  statement,  or  when  the  compiler  reaches  the  end  of the
  5198.      redefinition file. 
  5199.      
  5200.          All of the prefix definitions should come  after  the  definitions
  5201.      for  the main table. For a good example, examine the WSKEYS file which
  5202.      comes with the keyboard remapping facility.  This  file  contains  the
  5203.      keystroke definitions to configure the keyboard like WordStar.
  5204.      
  5205.      
  5206.                                   SOURCE FILES
  5207.      
  5208.          Included  in  the editor package are the source files to the above
  5209.      mentioned utilities. We request that if you improve  these  utilities,
  5210.      that  you  send the source back to us so that we can incorporate it in
  5211.      future releases. In exchange, you will receive a free copy of the next
  5212.      release of the editor.
  5213.  
  5214.  
  5215.  
  5216.  
  5217.  
  5218.  
  5219.  
  5220.  
  5221.  
  5222.  
  5223.  
  5224.  
  5225.  
  5226.  
  5227.  
  5228.  
  5229.  
  5230.  
  5231.  
  5232.  
  5233.  
  5234.  
  5235.  
  5236.      Remapping the Keyboard                          Appendix A  Page 4
  5237.  
  5238.  
  5239.                                 ME USERS MANUAL
  5240.  
  5241.  
  5242.  
  5243.  
  5244.  
  5245.  
  5246.                                THE CTAGS UTILITY
  5247.      
  5248.          If  you  are  working  on  a  large project, your source code most
  5249.      likely  resides  in  several  different  files.  The  CTAGS   utility,
  5250.      originated  in  Berkeley UNIX (UNIX is a trademark of AT&T), helps you
  5251.      create a little order out of your C files. The CTAGS utility  keeps  a
  5252.      record  of  the  name  of each function declared in your source files,
  5253.      and which file the function occurs in. By using the CTAGS  utility  in
  5254.      conjunction with the <GOTO FUNCTION> command (the CTRL T key), you can
  5255.      specify  the  name  of  a function and have the editor move you to the
  5256.      point of the function definition. 
  5257.      
  5258.          As mentioned above, the CTAGS utility creates a file called "TAGS"
  5259.      which  resides  in your current directory. The TAGS file has a list of
  5260.      all of the functions that you declared in specific source code  files,
  5261.      the  full  name of the file in which each function was declared, and a
  5262.      pattern to be used by the the editor's <SEARCH> command.
  5263.      
  5264.          To invoke the CTAGS utility, use this command from the DOS prompt:
  5265.      
  5266.              CTAGS filename1 [filename2...]
  5267.      
  5268.          The file name can have wild-card characters in  it.  To  create  a
  5269.      TAGS  file  for all of the source files in your current directory, use
  5270.      the command
  5271.      
  5272.              CTAGS *.c
  5273.       
  5274.          When you use the <GOTO FUNCTION> command (the CTRL T key), you are
  5275.      asked  for  the name of the function that you would like to go to. The
  5276.      <GOTO FUNCTION> command then reads the TAGS file, and attempts to find
  5277.      a line in the TAGS file which contains the name of  the  function  you
  5278.      want  to visit. If it's successful, another window will open up on the
  5279.      screen, and the cursor will be positioned on that function definition.
  5280.      
  5281.          In order to keep the TAGS file up-to-date, you may want to  invoke
  5282.      the  CTAGS  utility at periodic intervals. If you delete a function or
  5283.      move a function from one file to another without  updating  the  CTAGS
  5284.      file,  then  the  <GOTO  FUNCTION> command won't be able to locate the
  5285.      function.
  5286.      
  5287.  
  5288.  
  5289.  
  5290.  
  5291.  
  5292.  
  5293.  
  5294.  
  5295.  
  5296.  
  5297.  
  5298.  
  5299.      The CTAGS Utility                               Appendix B  Page 1
  5300.  
  5301.